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CHAPTER | 
INTRODUCTION 


U 


TREE SYSTENS has aipuei this docuaent as a guide to the use 
of any word in TREE-FORTH. This manual is not eeant to be a 
tutorial for learning FORTH. We recossend the book STARTING FORTH 
by Leo Brodie which is published by Prentice-Hall and can be found 
in sany book stores. 


WHAT 18 FORTH ? i 


FORTH is a coaputer topie as is BASIC. It was first developed by 
Charles N. Noore in the late s rties, The lan uage was conceptualized as a 
user friendly, 117 level coaputer language. the first elesent of FORT 

to appear was the text interpreter at STANFORD 1960's. 
This version shows the process of executing a prograe 
attached to a defining word. 


Moore iaplenented the first version of FORTH on the 18M 1130 cosputer in 
the late 1960°s. The naee FORTH, itself, is an abbreviation for fourth, to 
denote a fourth peritia cosputer language, The <i was changed 
because the IBN 1130 accepted aylan ter identifiers, eore coapler 
version of FORTH appeared in 1972 after Moore developed a ‘°Radio-Telescope 
Data Acquisition Progras® at the National Radio Astronoay Observatory (NRDA). 
Finally, in 1973, FORTH Inc. was fer sed by Moore and was sade available to 
the public. Soon a host of companies were selling FORTH for a variety of 
FORTH is now available for be teal 11, Heath WH-89, IBM 
PC, TRS 80, PDP-11, LSI-11, and for systeas using the 8080, 8084, 4800, 1802, 
6582, 180, and other aicroprocessors. 


Noore also established the FORTH INTEREST GROUP. Through this group the 
fig-FORTH standard was developed. Mere possible, TREE SYSTEMS has insured 
that TREE-FORTH aatches the fie-FORTH standards. TREE SYSTEMS was not able 
to include all of the fig-FORTH coneands due to lack of sesory space. Also, 
TREE-FORTH includes sose non-standard coasands so that aulti-tasking can be 
accoeplished. 


TREE-FORTH is geben > This gives the prograeser the ability to 
write real-tiee routines as is described in chapter 14, 


TREE SYSTEMS believes that it has ieproved in soe ways on the fig-FORTH 
standard by making TREE-FORTH a cospiler directive language instead of inter- 
etive. Interpretive FORTH contains a series of addresses for each coneand 
or word), These addresses ere stepped through by an inner interpreter which 
requires approxisately 70 bytes of code. The inner interpreter requires 170 
T states of execution tise 130 usec) on a 180. This inner. interpreter is a 
routine which sust run as overhead for every address interpreted. A coapiler 
directive language contains a series of calls to subroutines in each comaand 
or word. Therefore, the averhead of an inner interpreter is not necessary. 
The result is that coapiler directive FORTH is quicker than interpretive 
FORTH in eost prograsaing applications. 


in the earl 
section o 


sicroprocessors. 


Since TREE-FORTH is not an interpretive 157 25 but instead is a coe- 
piler directive phe it should not really be classified as a TIL 
(Threaded Interpretive Language). Instead it would be better to call the 
language a Threaded Coapiler Language. 
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WHAT 1S TREE-FORTH ? 


TREE-FORTH contains aost of the standard FORTH comeands. The language 
of FORTH is a structured prograseing language which allows the user to aanage 
and manipulate all of the dynzeit sesor y addressible by the sicroprocessor. 
FORTH is also a language in which the user can link down to schine code rou- 
tines and in this respect, FORTH is only a step above asseably level srograe- 
aing. FORTH is However a high-level user friendly language in that if allows 
the user to create his own coneand set. The entire prograe set written in 
FORTH is a customized set of instructions and in this way approches other 
high level languages. 


In addition to the standard attributes of the FORTH language, TREE-FORTH 
adds extra flexibility with its rill tg Multi-tasking allows the user 
to schedule progran to run at any tiee in the future. This is a feature 
available only on euch aore expensive systeas, With the proper hardware 
supper, a multi-tasking systee can be used as a real-tise controller, This 
aeans {hat the computer can operate at a speed sufficient enough to contro! 
the environeent as events occur, A aulti-tasking systes can also be used to 
enter data froa a real-tiee environsent. An exaaple would be sampling the 
breathing cycle of a patient in the hospital in order to deteraine his or her 
respiratory rate. A aulti-tasking systee also gives the user the flexibility 
of aren a program to run in the background (it 76 possible to run one 
prograa in the background while editing another in the foreground). 


FORTH is somewhat harder to learn than BASIC, however the flexibilt 
gained with FORTH sakes it a desirable prograseing language for eost if nal 
all prograsaing tasks. 


enen, 
t 

l A TECHNICAL DESCRIPTION OF FORTH FOLLOWS. $ 
t 

CUCU COCO 


TREE-FORTH” makes the Sinclair 2181 or TIMEX Sinclair 1000 a single user 
oulti-tasking systee. 


Exaeples 
TASK tasknase prograenase 
IN 20 TH taskname EVERY I TS tasknaee 


Twenty sinutes after entering these lines the pr ogr 28, prograsnase, will 
execute and continue recat lon iad | one second thereafter, Ten tasks eay be 
scheduled to run sisultaneously, Prograa pr or dne could, for instance, 
read a teeperature and display it on the screen, 


Tasking Faforsations 


ı Event Scheduling: 
8 Schedule with AT, IN, EVERY coseands 
$ Task at 1/40 th of a second (ear i eus resolution) 


-Task Options: 
8 LOCK, UNLOCK, START, STOP, RUN. 
t Up to ten tasks can be scheduled at a tise. 
è Tasks can be linked to ran in the background. 
! Each task has its own 32 bit clock. 
8 Tasks await execution in 63 deep event que. 
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ni que Editor: i 

User defined split screens. 

Visual editor with blinking cursor. 

Run editor while execution screen is running progr aa. 

Cursor Oriented. 

Delete lines or characters. ' 

Store line in pad. 

Insert lines froe pad to editor screen, 

Autoeatic character insert, 

Cospile any Line in, the editor screen. 

Coapile the entire screen. 

Cassette 1/0 (INPUT/OUTPUT) routines use the editor 
screen for reading information or loading infor eat ion. 


co 62 om co c „ co cp oo 


“Other Inforaation: 
8 TREE-FORTH uses all ASCI! characters, 
8 Extreaely Fast, Run 30000 0 DO LOOP in one second. 
8 High Priority Clock runs constantly for detection of stack 
under flow, 
3 Has a 16 bit nuaber stack and an B bit character stack 
separate fros the processor stack. 


Mote: Your systea aust have 2 KB of RAM in order to run Tree-Forth. 
Any wenory pack will provide enough eeaory. 


‘Forth is resident in an B K EPROM housed on a circuit board within the 
21-81. One can switch between Forth and BASIC using an external switch or 
the channel sellect switch on the bottoe of the coaputer.' , 


Since TREE-FORTH is resident on an EPROM, the inforeation on the chio 
can be erased by . exposure to ultra-violet light. TREE SYSTEMS can 
reburn any existing chip to update it to a new version. fs the latest 
versions of the language becoee available, TREE SYSTEMS will burn any 
changes into existing chips for a fee af $12.69. 


Also, for a developeent fee TREE SYSTEMS can add any custosized words to 
he E RUR. i 


For further questions or requests, please aail correspondence to: 


SOF TRAGIC: CORP, 
1210 U. tt st. 
BRYAN, GHIG 43506 
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CHAPTER 2 
INSTALLATION 


2.1 SET-UP 


TREE SYSTEMS sells TREE-FORTH for the 7XB1/TS-1000 already installed in 
a Sinclair computer, or as an extension to units already purchased. 


If you have an EPROM extension you will want to follow the following 
instructions to set-up your FORTH systee. 


STEP ia Take the cover off the Cosputer. There are five screws in the 
bottoe of the case. (Three are under the pads; the pads are attached with 
adhesive and are easily reaoved.) The case is shown in figure 2.1. 


After Tee the screws, the two halves of the case are easily sep- 
arated. ont he case will reveal the underside of the printed circuit 
board. Renove the two screws in this board as is shown in figure 2.2, Next, 
flip the circuit board over aking sure that the ribbon cable to the keyboard 
does not pull out. : 


At this point you should be looking at the various integrated circuits 
on the board. Identify the BASIC ROM chip. You can find a picture of the 
circuit board in * BASIC aanval. In the SINCLAIR book the picture is on 
page 119. In the TIMEI book it is on page 121. 


Resove the BASIC ROM chip | eying up one side with a butter knife or 

another flat device. de careful not to bend or touch any of the pins--the 

Te 753 easily damaged by static electricity. The socket is shown in 
gur e 0 . 


STEP 21 Reeove the TREE-FORTH circuit board fros the alueinus foil and 
styrofoae being careful not to touch the pins. 


It is recossended that before 15 include your BASIC Ron on the TREE- 
SYSTENS ‘circuit board, insert the FORTH circuit without BASIC. In this way 
ou can test the TREE-FORTH systes. Insert the circuit board as shown in 
i 2.4. There will be a grous of resistors which will interfere with the 
FDATH board. Bend these over, saking sure that there are no aetal-to-setal 
contacts. (Bent resistors are shown in figure 2.3) 


Wert, tura the SINCLAIR circuit board over and secure it with two screws . 


you reeoved e Then, replace the cover and insert the five screws 
previously resoved iros the holes in the cover. At this point TREE-FORTH 
will de operational (note that no BASIC will be available 


n this config- 
uration.) 


THE CASE 
FIGURE 2.1 


CIRCUIT BOARD SCREWS 
FIGURE 2.2 


THE SOCKET AND BENT RESISTORS 
FIGURE 2.3 
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INSERTING THE CIRCUIT BOARD 
FIGURE 2.4 
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2.2 INITIAL POWER-UP 


After Tht e step two of the assembly, the systea is ready for 
over up, This section will describe for. you how the various screens in 
REE~-FORTH should look when be first turn the power on. After inserting the 

power line on the coaputer the screen should look like Figure 2.3. If the 

screen did not cose up, insert the power line again. You can also try a cold 
restart. This is accoplished by holding the SHIFT key and SPACE key down 

Sisultaneously for about a half second, 


TREE SYSTEMS checks all the circuits before they are shipped to insure 
Proper operation. It is possible that damage occurred during shipping. 


Here are sone possible reasons why your screen did not cose up properly: 


— Did you correctly insert the TREE SYSTEMS circuit board into the RON 
socket? The pins fit tightly, so do not be afraid to apply a 
little pressure. 

— Did you bend oy of the circuit board pins over during installation? 

— Bid Sh put the circuit board pins in the correct holes in the 
socket? Soee sockets are 78 pin sockets, The holes 1, 2, 27, and 
28 should remain 10 

— Whea you bent over the resistors, did you Bake sure that none of the 
wire leads where touching)? 

— or bogs RAM pack attached properly? It the connections are not 

e 
1 


z 


U 

systea will not display the video inforeation. It is best to 

eave the RAM pack off lif you have a 2 KB systes). Reseve the 

pack and. then try to power-up again by reeoving the powerline and 
re-inserting it. 


If you have other problees a "y call TREE SYSTEMS and we will try to 
help you trouble shoot i installation over the phone. 
Calls 1-616-245-7533, 


TREE-FORTH BY TREE SYSTEMS 
COPYRIGHT (c) 1983 
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Screen upon poan 4 COLD reset 
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imere ate 40 sets of screens in TREE-FORTH, The first one we have 
seen. The second one is a split screen. To display the split screen, hold 
down the SHIFT and EDIT keys simultaneously., Now the screen should appear as 
shown in Figure 2.6. 


This is the editor portion of 
the screen. It is referred to 
as ED In software. 


This is the rua tise portion 


It is referred 
console in 


of the screen. 
to as CO of 
software. 


EDITOR SCREEN 
FIGURE 2.6 


You con toggle between the two portions of the split, screens by depres- 
ing the Nair ond EDIT keys. 


To leere thet your systee is running properly, type the following in 


the execution portion of the screens . 
Ain (ENTER) This will display all of the TREE-FORTH words 
presently ia cry. 
CPU CENTER) 


This indentifies the ee of processor which is 
presently ruaning. (A 280 in the 18-1000) 


2.3 WARN ANO COLD RESTART 


The TREE-FORTH caa be re-initialized fron software anytise without 
having to pull out the power supply line. 


A. WARM RESTART: WARN (ENTER) will execute a were restart. 


A wara restart can also be accoeplished by holding BREAK (SHIFT/SPACE) 
down for an instant. 


A ware restart resets the stack pointers to the absolute bottoe. The 
systea then checks for a catastrophic error such as an overwrite of the 
mates variables. If necessary, a ware restart calls ‘a cold restart to 
recover. The editor is reset to the CONSOLE screen. pial if the task 
115 5 OFF . TOFF) any background task is set to a nu { progran and 
’ asks re ed. 


ey 
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B. COLD RESTART: COLD (ENTER) A cold restart is accomplished by 
holding the BREAK key down for about a half second. 


A cold restart reconfigures the entire systee and brings up the original 
screen, as if the power were just turned on. Note that all working eeeor 
IRAN $ 4000H) is erased. Cold restart also checks for the asount of RA 
attached to the Sinclair and stores this value in a system variable. 


2.4 SYSTEM RESPONSE AND ERRORS 


TREE-FORTH proepts the user with an OK after each successful operation 
in the execution screen. The operation aay be something as sieple as petting 
a nuaber on the stack, or as coep i cated as an entire line of pr ogr 28. As 
Jong as no error is found, the system reports with an OK. 


If some error should appear during an operation, an ERROR statesent will 
de displayed on the screen followed by an error code. A description of the 
error codes can be found in appendix B. 

2.5 SWITCHING BETWEEN TREE-FORTH AND BASIC 

The circuit board supplied by TREE SYSTEMS can also be configured to 
allow the user to switch between BASIC and TREE-FORTH. If you wish to do 
this, follow the instructions below. (This will require sone soldering.) 


STEP 11 Follow the sane procedure as required for inserting the TREE- 
FORTH circuit board. In this case, resove the circuit board fros its socket. 


STEP 21 Insert the BASIC ROM chip next to the FORTH chip as shown below 
in Figure 2.7. 
[] 


4 


INSERTING THE BASIC ROM 
FIGURE 2.7 


Pren a 1% 


Alter properly inserting the BASIC ROM, solder the pins in, 


STEP 2: There is a seall juaper wire which is wired fros a socket in the 
oard to the ground plane (the large asount of interconnected Silver on the 
card). Resove this wire 1 heating the solder and pulling the wire out with 

long-nesed pliers. Take a long piece of wire and put it into the sase 
ole. 


FOR AN EITERWAL SWITCH: Tate the free end of the wire just attached to 
he circuit board, and attach it to one side of a Single Pole Single Throw 
SPST) switch, The other side of this switch should be wired to ground. You 
an use the ground plane on the TREE SYSTEMS circuit board or the ground 
lane oa the T/S coaputer. 


FOR THE CHANNEL SELECTOR AS A SWITCH; You @ay also elect to use your 
angel, sellect E as the sujtch for toggling between BASIC and FORTH, 
2 do this, take r Circuit board and attach it to the 
eater fos oa the chanael sellect switch. This is shown in figure 2.8, 
RIH will be channel J and BASIC will be oa channel 2, 


One aote: You wil) have to re-power when you switch froe FORTH to BASIC 
' order te reinitialize the BASIC systea, 


You aay also elect to put an extension EPROM or RON 
c When floating point arithaetic becoses available 
it will be in the fore of an extension EPROM, for inforaa- 
oœ oa floatlag point, contact TREE SYSTEMS and ask for the Floating Point 
tension for Tree-Forth. 
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FIGURE 2.6 
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CHAPTER 3 
VISUAL EDITOR 
THE EDITOR 


TREE-FORTH for the Sinclair uses ASCII characters, ASCII stands for the 
*Aserica Standard Code for Inforaation Interchange", which is the industry 
standard. A coaplete listing of the ASCII code can de found in appendix A, 
This is a deviation iroa the Sinclair BASIC. It uses its own, non-standard 
character set. Using ASCII gates the system auch aore flexible in teras o 
cossunicating with existing coaputer systeas (aost of which use ASCII to 
Cossunicate fo sodeas and printers). 


The visual editor is a screen editor, not a line editor. This gives the 
user a great deal of flexibility in writing FORTH progr 6s. 

TREE-FORTH uses to screen areas so don’t be confused. The first screen 
appears when yu turn on the power, (See Fig. 2.5). The second screen is 
apas with the SHIFT/EDIT set of keys. Once fa are in the second screen 
(FIG. 2.6) you can use the in ortion for editing, The lower portion is 
an execution screen (This wll also be Called the console.) The two halves 
are separated by a black band called the video pad. You can switch between 
edit and execution screens using the SHIFT/EDIT keys. 


J. THE FOLLOWING ARE EDITOR COMMANDS 


Note: If you hold any key down for sore than one second, 


the depressed 
key will repeat. 


HIS NOVES-THE CURSOR ONE LINE DOWN, 
8 one THE CURSOR ONE LINE UP. 
WIS NOVES THE CURSOR ONE SPACE TO THE RIGHT. 
S ps IN THE SLOT WHERE THE CURSOR iS PRESENTLY 


SHIFT / 4 1 DELETES THE LINE ON WHICH THE CURSOR IS POSITIONED, 
SHIFT / RUBOUT : DELETES THE CHARACTER AT THE CURSOR POSITION. 
(RUBOUT aay be labeled DELETE on sose keyboards) 


Note: On the editor screen, depressing the ENTER key (NEW LINE on sose 
sodels) aoves the cursor down one line; it does not coapile the line. 


Also, continued typing on a line will provide iasediate wraparound onto 
the next lige Should you type beyond the end of the screen. However, if i 
90 back and insert Characters in full lines, they will not wraparound, 
Stead the end characters will be lost off the right side of the screen. 

Note: The insertion sode is autoaatic, Typing a character in the eiddle 
of a line soves all the characters following the Cursor to the right. 


1 eT) 
4 Ide following cosaands deal $ 
with the video ps: t 
The pad is the black band be- 3 
tween the editor portion and the . 
execution portion of the screen. § 
MAUL TT TTT 


SHIFT / 31 gg A LINE ON WHICH THE CURSOR IS LOCATED AND PUTS IT IN 
SHIFT / 2: TAKES THE CONTENTS OF THE PAD AND INSERTS THEN ON THE LINE 
OF 1 EIRSIR, IT THEN SCROLLS PRESENT AND FOLLOWING 


KEY SHIFTED KEY SHIFTED. KEY FUNCTION 


1 H EDIT ! Switches between screens 

2 1 AD i Fetches a line from the video pad 
3 1 THEN 1 Puts a line in the pad 

11 10 1 Deletes a line from the editor screen 
S$ ot: c { Moves cursor left 

4 H v H Moves cursor down 

7 f 7 H Maves cursor 

8 l -) { Moves cursor r 

9 J GRAPHICS ! Inserts line on editor screen 

O $ DELETE 1 OBeletes J character 

9 1 ra !  Coapiles an editor screen line 

1 1 OR ! Stores conssand. Displayed as ! 

E 1 STEP ? Fetches coseand. Displayed as @ 
R 14 t Character: C 

T t 0O Character 1 

11 $= Character 11 

9 1 $ 1 Character 18 i 

l ! ( l Character 1 

0 1 ) f Character 1 

P l s Character 1 

A I STOP $ Clears the present screen 
S 1 (PRINT 1 Character 11 

1 SO { Character: ’ 

F 1 FAST 1 Character 11 

6 t LLIST : Character 1“ 

9 1 {Characters @ 

1 1 - I Character 1 

K I + 1 Character 1.“ 

L t z 1 Character : = 

ENTER! FUNCTION  ! Howe 1 Cursor to upper left corner 
SHIFTI SHIFT { 

11 3 ! Character: 3 

1 3 j Character : j 

( 3 1 Character : 

91 / ! Character: / 

U l (] H Character 1 8 

nf ( { Character: < 

N l ) i Character :) 

. 4 ’ 1 Character: , 

SPACE! Special WARN Restart 


H 
3.2 COMPILATION OF CODE. 


The following coenands deal with the coepilation of code from the editor 
Screen. There are two ways to write code in TREE-FORTH. The first is to 
enter cosnands one by one in the console screen. (The console screen is 
defined in chapter 2.) The aore desirable aethod of writing code is to write 
a series of words in the editor screen and then either coapile the entire 
NN or compile the lines one by one. This allows you the freedoe to go 

ack and change things in the editor screen and recospile. 


a Paaa . it 


If held for 1/2 second COLD restart 
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The coseands below deal with coepiling code froa the editor screen. 


SHIFT / Q s COMPILES THE LINE OF CODE ON WHICH THE CURSOR APPEARS (The 
Ag line appears in the execution screen after this 
coaaand, 


Note: A Forth word may be sore than one line long. In this case 
will have to place the cursor on the top line, cospile it, and then eove the 
cursor to oe the rest of the line. Do not worry about the compiler, it 
will wait until it finds a semi-colon (;) before it assuees that the end of a 
Forth word is reached. 


If the line is successfully coeplied, an OK will appear at the end of 
the line. If the line does not coapile brane due to a prograssing error, 
then ERROR will be displayed followed by the appropriate code. The error 
codes are found in appendix B. 


CPL: COMPILES THE ENTIRE EDITOR SCREEN. 


Use this comaand after you have filled the entire editor screen and wish 
to coepile all the statesents. This is also very useful for cospiling 
screens after they have been downloaded droa the cassette tape. 


NOTE 1: You do not have to write all of your code in the editor screen 
and then 171 808 it. You can coepile FORTH code line by line in either 
SCREEN 1 (FIb. 2.5) or in the execution portion of SCREEN 2 (FIG. 2.6). 
Each word that you type while on the execution screen is cospiled iesedi- 
ately. „It is for this reason that using the editor to hold uncospiled code 
is desirbable, You can aake corrections to the eiddle of a prograa before it 
is too late to change it. 


NOTE 2: The editor screen can be turned off in order to sate the present 
screen only an execution screen. 


Coseand: EOFF 1 Turns the editor screen off. 


As an exacple Enters 
EOFF (ENTER) 


By repeatedly pushing the ENTER key, you can scroll the editor screen 
off the top of the screen. The editor screen can be turned back on by typing 
SHIFT/EDIT keys sioultaneously. 


3.3 CREATING SCREENS 


Any nuaber of screens can be created using the SCREEN coseand, A screen 
is a portion of the video display in which characters can be placed. You can 
have as Bany screens as m wish and they can be any rectangular size, 
ranging from one character by one character to as large as the screen itself. 
lf a screen is defined outside the bounds of the video display, the screen 
will be defined in RAM outside the bounds of FDOOH to 10000H (video RAM). 

Note: screens can overlap but no provision is sade to keep one screen 
froa intefering with another if this is done. 


The definition of a screen is outlined below: 


a b c d SCREEN ase 


à > coluen pusber of upper left hand corner. 

b = row nuaber of ve left hand corner. 

c colues aweber of lower right hand corner. 

d = row nusber of lower right hand corner. 

nane = this can be any screen nase desired by the user. 


0 0 13 13 SCREEN 51 (ENTER) Ibis command will create a 


screen starting in row 1 coluan 
1 and continuing to coluen 16 row 16. ' 


To display sonething on this screen, type 1 
oo THERE ° S1 .W (ENTER) 


Screens are defined in the dictionary. They can be disabled by FORGET- 

TING thea just as you would forget and Forth word. 
FORGET 81 (ENTER) would disable screen 81 

bo screen also has an identifier which aust be used with certain 
Consands that deal with different screens. Sose of these words are REV , 
„ C, and will be discussed in later portions of the aanual. When you 
powerup, two screens are already defined. The dosinant screen is the console 
screen or execution screen and has an identifier of CO. The editor screen 
which is enabled by hitting the SHIFT/EDIT keys has an identifier of ED. To 
use words which direct output to different screens use these identifiers. 


CO : Console screen identifier, ‘ 
ED ¢ Editor screen identifier. 


3.4 FAST, SLOW, AUTO 


TREE-FORTH still accepts the SLOW and FAST commands as does Sinclair’s 
BASIC. Ia FAST eode, the video telir is turned off until the CPU finishes 
ocessing the prograe, In SLOW „„ the video display always resains on 
oaly 20 percent of the processing tiee is used to execute the prograa, 

the other 80 percent is used to update the display. 


The individual keys no longer initiate the SLOW and FAST coseands. 
Instead, you aust type thea in letter by letter. 


TREE FORTH also supports the coesand AUTO. AUTO will interrupt the 
„ if the processor requires aore than 1/4 second to execute a 


It is also possible to gate any Screen reverse video. The word REY 
along with the screen identifier is used to toggle the screen froe reverse 
video te corsa or vice versa. 


CO REV will sake the console screen reverse video. 
ED REV mill reverse video the editor screen. 


REV: Executed after a screen identifier to reverse the doainant 
background field. (reverse video or noreal video) 


/ 


CHAPTER 4 
MASS STORAGE AND RETRIEVAL 


4.1 STORAGE 


Note: ' Both load and store will teaporarily stop video output to the 
screen. The timing required to store or load screens requires ass of the 
rocessor tise. Because no interrupts are issued during the cassette rou- 
tines, all tasking is suspended. 


TREE FORTH allows for the storage of screens or a Series of screens on 
magnetic cassette tape. Note that fhe whole editor screen will be saved, 
thera ores aake sure that only the inforaation you want to save appears on 

at screen, 


STORAGE COMMAND 


Storage takes place fros the editor screen. (This is the portion of the 
video display above the black band as shown in figure 2.6.) Each screen is 
loaded with an identifying nueber. 


You should take care to reseaber which nuaber a specific screen is, 40 
that if a large nusber of screens are stored on a tape each one will nol have 
to be viewed 0 find the ia forest ien you want. 


Sisplest case: ` 


Fill the editor, screen with any inforeation which you desire. After 
1 finished go to the execution screen.  (Accoaplished by typing SHIFT/ 
) 


Such a screen sight look like: 
THIS SCREEN WILL BE AN EXAMPLE 
SHOWING ONE 


MIGHT STORE 
INFORMATION ONTO THE TAPE. MOTE 


THAT THIS SCREEN DOES NOT HAVE 
10 BE 


A e A SCREEN 
312 BYTES OF INFORMATION. YOU 
CAN STORE ANY SE 


Wenne 
10 STORE (ENTER) 


Next, load the screen with any inforsation which desire. You can 
even use the exaaple above. Then, store the screen onto the tape by typing 
the following as shown above: 


10 STORE (ENTER) 


Reaeaber that there is actually a five second leader on aost 
tapes which can not be taped over. 
seconds before storing inforaation. 


cassette 
Therefore, advance the tape at least ten 


What does store actually do? Here is 2 description:“ 


STORE : Takes a nuaber off the user stack, in this case ten, and stores 
the editor screen with the nusber as an i denti fler. 


Note that you can only store inforaation {roa the editor screen. fou 
can not store inforaation from the execution screen (also referred to as the 
console screen). This should not be a problem, because for aost large pro- 
graas, you will be working in the editor screen, 


4.2 RETRIEVAL 


To retrieve inforaation froe the pe, the LOAD coesand is used, 
0a 


As an 
erzeple, retrieve the sane screen we jus 


ded in the above paragraphs. 
The coasand is: 


10 LOAD (ENTER) 


- LOAD : This comsands takes the nuaber on the user stack as the screen 
nuaber to de loaded froe the tape. The routine will continue to 
look for the screen until it is found or until it is interrupted 
by hitting the space key. 


After typing 10 LOAD , rewind the tape so that screen 10 will surely be 
found, then press PLAY and wait for the computer to read the tape. When the 
screen is read fros the tape, the editor area will contain the saae infor- 
ation that it contained when it was loaded on the tape. 


Special Note: Typing O STORE will insure that the screen will be 
the first loaded no aatter what nuaber is specified with LOAD. 


Typing o LOAD will load the first screen found on the tape regardless 
of the screen nuaber, Also, all subsequent screens (after the first screen) 
can also be loaded using the --) coseand described below. 


INTERESTING INFORMATION: TREE-FORTH allows any inforaation on the editor 
screen to be stored and loaded. The contents of the screen do not have to be 


FORTH words or definitions. ZIBI BASIC does not allow this. With Tree- 
Forth you have a way to store any inforaation that you wish (letters, etc.). 


4.3 LOADING AND COMPILING SCREENS 


When loading any program fros the tape to the editor'screen, all of the 
code on that screen can be coapiled as soon as it is loaded. 


CON : The comeand to turn on the automatic screen cospi ler. 
COFF : The coaaand to turn the autosatic screen coepiler off. 


As an examnle create a Sieple 11 on the editor screen and store it 
on the tape a reen one. Now use the following copeands: 


CON 1 LOAD (ENTER) This will automatically coapile the screen which has 
been loaded fron the tape. 


Note: 


The screen cospiler defaults to off on initial power wp, or on a 
COLD restart. 


4.4 SEQUENTIAL SCREEN LOADING 


Th gay be wany tises when your FORTH prograa is longer than one 
Gen. in this . each screen aust be loaded and coapiled before the 
next screen can be loaded. The instructions for doing this are found belon, 


It is iaportant that you store w screens in increasing sequential 
order if you want to load and coapile thea in sequence, 
To store screens onto the tape in sequential order, you ay «se the 
following comsand: 
(-- : This comsand stores the present editor screen with a screen nuaber 
which is one larger than the last screen stored. 


In order to load screens sequentially, the cossand is: 


--) ¢ This  syabol, when placed at the bot tos of the editor screen and 
coepiled, increaents the screen count and loads the next screen by 
incresenting the screen count. 


PAGE s This is an INTEGER variable which contains the sost recently 
accessed TOREJ or LOADed page nuaber. 


-INTEGER contains the address for the address to which the 
a Soret dowaload and froe which the tape is loaded. The default 
value is the origin of the display buffer. 


Warnings If are coapiling each screen as it is loaded sequentially, 
you aust sive the eesti ler pn lice to coapile each screen. 


There are two ways to accoeplish this: 


. the tape after each screen has been loaded and is coepiling. 
thea 0 9 T ready to load another screen (horizontal lines 
appear) restart the tape. 


2. 1 large blank spaces aro left on the tape when you are saving 
sequential street, there nete be enough tiee to compile each screen before 
the next one is to be loaded. 


Either of these methods should insure that the next screen on tape will 
aot be’ played“ before the cosputer is ready to receive it. 


CHAPTER 5 
DESCRIPTION OF STRUCTURE AND COMMAND FORMAT 


5.1 STACK STRUCTURE 


FORTH is different froe sost other cosputer 5 bees in that it uses a 
stack. A stack stores things in the order in which they were entered. 
Itens can be reeoved with the last itea first. Here is an exaeple: 


Configure pe miu so that you are on SCREEN i. or the execution 


portion of SCREE ater three nuabers: 
O 1 2 (ENTER) The stack looks like thiss ö 
2 top ' 
0 dot tos 


To display the top itea on the stack, sieply type: 
„ (ENTER) 

This will resove 2 from the stack and display it. Typing: 
e (ENTER) a second tiae will display the 1. 


All the sathesatical meer ations are also per for sed on the stack. To 
exasine this, type the following: 


023 (ENTER) The stack looks like: 
3 
í 5 
Now type: nh, 
$ (ENTER) This cosaand takes the top two entries off of the 
stack, aultiplies thea, and puts the result back on 
the stack. The result is: 


6 
0 


If another eultiplication were per for ged, then: 
$ (ENTER) Would leave as 
0 16 90 00 
All of the comsands in TREE-FORTH use a stack. TREE-FORTH has a separate 
O bit character stack and a 16 bit auaber stack. You will be using the 
mueber stack sost of the tise, The character stack is described in sore 
detail in the chapter on character input and output. 
Li 
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NOTE: For those of you who are interested, both the character and nuaber 
stacks are separate froa the processor stack. The character and nusber 
stacks are resident in RAM. This allows you to do sose really interesting 
cringe in software. The number stack pointer is contained in the IY register 
of the 180 sicroprocessor. The character stack pener is stored ia aesor 
at address FCOAN, Because of the unique way the Siaclair’s aesory is — 
this address is accessible with 2 KB, 16 KB, 32 KB, or 64 KB of sensory. 


5.2 DICTIONARY AND ITS USE 


After reading the above section you should have a feel for how the 
nuaber stack works. TREE-FORTH words are stored in another place in eenory, 
the dictionary. The rob haat | grows up froe 4000H. Every FORTH word i 
stored in aesory with a header, The header contains the nuaber of characters 
in the word plas the characters of the word itself. The nusber of characters 
plus the characters theaselves are used by the outer-interpreter when a 
search Of the dictionary is aade for a word. 


The eee can create new words in the dictionary using various 


Coop liers: hese cospilers are described in detail in the following chap- 
ers. 


Here is an exaeple of how a new word would be defined sins the COLOW/ 
SEMI-COLON compiler. To create a word which takes the average of two weder t 
on the stack and displays the result, type: 

1 AVG +2 / . 9 (ENTER) on the execution screen. 

t AVG 2 / 5 (SHIFT/E) os the editor screen 

The above prograa coeputes ienige by adding the top two values oa the 
stack and then pushing 2 on the stack and perforsing a divide, The period 
l. ) then takes the top value off the stack and displays it. 


The propras AVG can be used to take the average of tuo nusbers, Find 
the average of 86 and 46 by typing : 


06 4b AVG (ENTER) 
66 OK 
The answer bb is displayed to the screen. 
VARIABLES and INTEGERS can also be created in the dictionary. This is 
described in Chapter 10. 
3.3 COMMAND FORMAT 


Many of the descriptions of the TREE-FORTH cossands will be of the 
following fore. 


top --) steack stack ( top 
before after 
execution execution 


lich cossend is described by an exaeple. The state of the stack is 
showa bolero and after the coeeand is executed. The cosaands are first 
described im a generic format and then an erzeple of each one is given. 


What the variables aean: 


( ni,n2,n3,etc. } 
d : 1 1 aian 8163, d? ett.) sosetises alow and nbigh are 
used to describe how double nuabers appear on the stack or in 
ictionary. 
u * e al nusber addr = represents an address in menory 
b = byte 
ter 
i : boolean flag (o- alte, t#true) 


— — peter 


CHAPTER 6 
MATHEMATICAL COMMANDS 


0 


TREE-FORTH uses integer aritheetic. For some this aay be inconvenient 
at first. However, one of the coseodities a coeputer has is speed. Often- 
tiees it is desired that operations be perforsed as quickly as posie and 
in a 180 integer aritheetic is euch faster than floating poiat aritheetic, 
lf you need aore . in your values, the values can be scaled by a 
factor, for exaaple 100. Scaling by 100 would allow you to include cents in 
calculations based in the dollar and cents systea, 


Most 16 bit arithaetic is signed aritheetic in TREE-FORTH. However, 
sost 32 bit, and all bå bit aritheetic is unsigned. This may present a 
Ab ia ere you are not keeping track of the approzieate aagnitede of your 
calculations. 


Here is the difference between signed and unsigned ar i thsetic. Below is 
listed a chart showing the difference of signed and unsigned nuabers. 
the BINARY and HEX formats of the bit patterns for 16 bit nusbers are given. 
You can extend this for 32 and 64 bit nuabers. 


———— —õ—k— 2 


5 T F 5 H 
; UNSIGNED t BINARY i HEX SIGNED ! 
„ 55 „ 
1 15539 S unununum £ FFFF ! -i i 
l 65534 i ALLLLLELELNILITIO ; FFFE ! -2 l 
i 9 0 0 i 0 0 i ee 1. 0 0 KI f 
| l ! l i 
1 37169 H 1 8000 32708 
; 32767 oll i TFFF 32767 
l eave l 0 0 l oe H 0 0 0 H 
l l i i ! 
i 0 ˖ 0000000 000000000 0000 i 0 ! 


———— — ——— y UP—¶ o » p — — 


TABLE 6.1 
UNSIGNED, SIGNED, BINARY, AND HEX NUMBERS 


+ (ADDITION) : Adds the top two stack entries nl and n2 leaving the 
result on the stack. 


alta 
n2 


| 

2 
- (SUBTRACTION) :  Subtracts the top 
n2, and leaves the result on t 


1+. (ENTER) 


try , ni, fros the second entry, 
e top of the stack. 


h 
n-an „ benen, 


n? 


C{MULTIPLICATION) : Multiplies the top two entries, ni and n2, and 
leaves the result on the stack. 


al tn 248%. (ENTER) 
n 8 OK 


/ (DIVISION) : Divides the second stack entry , n2, dy the top stack 
entry, ni, and leaves the result on top. 


al n 62/7. (ENTER) 
n2 30O 
28 (MULTIPLY BY 2) : This aultiplies the top stack entry by tuo. 
al 28a 3 28 . (ENTER) 
6 OK 


2/ (DIVIDE BY 2) : This divides the top stack entry by 2. 
al 2/ n 42). (ENTER) 
2 OK 
ABS (Absolute Value) 1 Leaves the absolute value of the top entry on 
the top of the stack. 
al ABS n -12 ABS . (ENTER) 
12 OK 
WAI (Marieue) 1 Finds the largest of the top two stack entries and 
leaves it on the stack. 
ni MAY a 9 4 RAX . (ENTER) 
n2 i 9 OK 
NIN (Ninieua) 1 Finds the seal lest of the top two stack entries and 
leaves it oa the stack. f 
ni MIN a 9 4 NIN. (ENTER) ~, 
12 4 OK 


MINUS (Uniary ainus) s- Changes the Sign of the top stack entry. 
al-n JI MINUS . (ENTER) 
-31 OK 


+- (SWAP SIGN ) : lies the sign of the top entry, al, to the second 
entry, n2, 1 pi the fetm entry on the start, 


al +- n2 (signed) 2 -3 +- . (ENTER) 
n2 -2 
NOD 1 Perforas the division, n2/al, and leaves the 16 bit resainder on 
the stack. 
nl NOD ar 13 4 NOD . (ENTER) 
n2? 30k 


} 
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, 
* 
i 


IMOD : per for es the division, n2/nt, and leaves the repainder ni on the 
top, and the quotient, nd, on the dot tos of the stack. 


nl /MOD ni 5 2 /MOD . (ENTER) 
n n? 1 OK 
2 OK 
t/NOD :  Multiplies the second, n2, and thied, A entries and divides 


by the first, ni, leaving the remainder on the top of the stack 
with the quotient below it. ( Signed arithaetic ). 


ni 8/M0D nr 3 3 2 8/M0D . (ENTER) 
n2 nq 10K . (ENTER) 
' n3 4 OK 


Mt: This oultiplies two 16 bit nueabers, nl and n2, and leaves a 32 
dit result, d. 


ni Mod 20000 20000 N8 D. (ENTER) 
n2 400000000 0K 


/ 1 This divides a 32 bit nuaber, d, by a 16 bit nuaber, A, N 


16 dit remainder, nr, on the top of the stack and a {6 
quotient, nq, on the boltos, 


n N / nr 40000000 1 20000 . / . (ENTER) 
nq 1 OK . (ENTER) 
20000 OK 
(The dot before the 400000000 signifies that it is a double nusber. 
The dot aay appear any place in the nuaber.) 


MOS : 1 aultiplies two 32 bit nuabers and the stack leaving a 64 bit 
7 


esult, 
di MBS diow 
d2 dhigh 


MD/ : This divides a 64 bit nuaber by a 32 bit nusber, di, leaving a 
32 bit reeainder, dr, and a 32 bit result, dq. 


Dt s This aultiplies two signed 32 bit NN nuabers together and 
leaves a 32 bit signed result on the stack. 


d D d 30000. 25000. D. (ENTER) 
d2 750000000 OK 


D/ 1 This takes a 32 bit unsigned nusber and divides it by a 32 bit 
unsigned nueber generating a 32 bit remainder and a 32 bit quotent. 


* i 
SG 


t/ 1 Multiplies the second entry, n2, and the third entry, n3, and 
divides by the first, nl, leaving the result on the stack. 


al 8/n 
n2 
a 


By (32 bit add) 1 This is a double precision add which adds the top two 
32 bit nuabers found on the stack. 


di D+ di 400000. 40000. Dè D. (ENTER) 
d2 440000 OK 


D- (DOUBLE PRECISION -) : Per for es a double precision subtraction of the 
top entry froa the second entry. 


di D- d 
42 


DABS (DOUBLE PRECISION ABS) 1 This ie takes the absolute value of 
the double precison auaber on the stack. 


4638/7. (ENTER) 
8 0 


U 


di ABS d2 


DNINUS 1 3 PRECISION -) 1 Changes the sign on a double precision 
. meber. 


di DMINUS d2 40000, pelle D. (ENTER) 


-40000 


Ut (UNSIGNED u) 1 This sultiplies the two unsigned nuabers found on 
the user stack, leaving an unsigned result. 


ul US u 6000 6 US U. (ENTER) 
02 36000 0K 


UNOD (UNSIGNED HOD) : The second unsigned 32 bit double entry, u2, is 
divided by the top auaber, wl, leaving the unsigned reaainder. 


ul UNOD u 
ud? 
umd (UNSIGNED /NOO) : The second unsigned 32 bit double entry, ud2, 
is divided by the top nueber, ul, leaving the reaainder on the top 
of the stack and the quotient on the bottos, 


ul / 0D ur 
ud? ug 


23 


1111111111111 


CHAPTER 7 


LOGICAL OPERATORS AND 
COMPARISON COMMANDS 


7.1 LOGICAL OPERATORS 

AND : per for as a bitwise AND of the 16 bit nuabers on the stack. 
01 (8 bit ex) 
11 


AND 
5 00000101 
OR : Perfores a bitwise OR of the 16 bit nuabers on the stack. 


5 00000101 (B bit ex) 
9 00001001 


OR 
13 00001101 (132D in HEXADEIMAL) 
YOR : Perforas a bitwise exclusive-or of the 16 bit nusbers on the stack 


5 00000101 (8 bit ex) 
700000111 


106 
200000010 


result 


7,2 COMPARISON OPERATORS 


( Tf second stack oy is less than the first, the operation leaves 
al, otherwise it will leave a 0. 


ul (1 0 2 < . (ENTER) 
u? { OK true 


>s second stack entry is greater than the first, the operation 
leaves a 1, otherwise it will leave a 0. 


' ul) f 02). CENTER) 
u2 0 OK false 


4 
O= : Tests whether the top stack entry is 0. 
leaves a I on the stack, otherwise 0. 


ul 0: f 13 02 . (ENTER) 
0 0K false 


If it is, then operation 


30 


0) : Tests whether the stack entry is positive. If nuaber 15 positive, 
the operation leaves a 1, otherwise it will leave a 0. 


ul 0-4 


If the nuaber is nega- 
I 


O : Tests whether the stack etry is negative. 
tive al is left on the stat » otherwise a 0. 


ul 0% 


2: Tests whether the top two stack entries are equivalent. 
are, the operation leaves a 1, otherwise 20. 


ul =f 37 DUP = . (ENTER) 
u2 1 0K true 


C= : Just like = but it only checks the least significant byte of the 
two 16 bit operands. 


cl=f 259 J C= . (ENTER) 
c? 1 true (259 god 256 = 3) 


BC : Checks if the second 32 bit nuaber is larger than the first 32 bit 
number. If the operation is true, then al is left on the stack 
otherwise a 0 is left. This is an unsigned coaparison. 


di DÀ i 
d2 


If they 


D) : Checks if the second 32 bit nuaber is Larger than the first 32 bit 
Auaber. If operation is true, then al is left on the stack 
otherwise a O is left. This is an unsigned coaparison, 


di D> ¢ Pes 
d2 


B= : Checks if the two 32 bit fuabers on the stack are equivalent, 1“ 
they are, a! is placed on the stack, otherwise a O is left. 


d! D= . 
d2 


DAAI : Leaves the larger of the two 32 bit nuabers on the stack. This 
is an unsigned operator. -2. will be greater thin 2. 


di DAAI d 
d2 


DAIN : Leaves the seller of the two 32 bit nuabers on the stack 
iS an unsigned operator. 


di DNIN d 
d? 


. This 


DO= : Checks whether the 32 bit nuaber on the stack is equal to zero. 
If it is, af is left on the stack, otherwise a zero, 


d D= f 
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U: This is an unsigned less than Cosparison of the two 16 bit values 


on the top of 
stack. Otherwise, a zero is lett. 


ul be. 
u2 


he stack, It u2 “ 


ul, then 2 1 is left on the 


‘AD 


8.2 


3— 


CHAPTER 8 
NUMBER BASES and STACK MANIPULATION i 
NUNBER BASES 


Mote: On initial porer a: Tree-Forth defaults to DECIMAL. 
(BASE 10, 0 - 9 


DECINAL : Sets the current base to decieal (all entries displayed in 
base 10). 


HEX : Sets the base to heradeciaal, 
base | 


BASE : An INTEGER value used to aodify the current base of the systea, 
al 10 BASE 
BASE ni 


base 16 (all entries displayed in 


(loads the current base with ni) 
lol ces the current base onto the user stack) 


3 TO BASE (ENTER) (changes the current base to 3) 
DECIMAL 532 3 TO BASE . (ENTER 
201201 OK (201201 is 532 in base 3) 

STACK MANIPULATION 

. 1 A period prints the top nusber stack entry. 


123. (ENTER) 
J (prints the sost recent stack entry) 


D. : Double nusber display. A double aueber is taken off the stack and 


displayed on the screen. 
where a signed 16 bit nesber ranges from -32768 - #32767) 


U. 1 Unsigned nuaber display. An unsigned nuaber is taken off the stack 
and displayed to the screen. 


S-)D : This is a 16 to 32 dit sign extension. 
d- : This is a 32 to 64 bit sign extension. ' 
DROP : Drops the top neater stack entry. 

15 DROP n2 


20ROP : Drops the top two entries (or a double nuaber) off the stack. 
DUP : Duplicates the top nueber stack entry. 


al OUP nl 
ni 


"OUP t Duplicates the top eatty only if jè ig onezer: 


(an unsigned nuabder ranges froa 0-65535 


OVER : Copies the second entry on the stack to the top. 


nt OVER n2 
n2 ni 
n2 


PICK i Copies the entry indexed by the top stack entry to the top. 
ni 3 PICK n3 
n? al 
n3 n2 
n3 (z 2 PICK is just like an over) 
SWAP : This coamand interchanges the top two stack entries. 
nl SWAP n? 
n2 nl 
DSWAP : This cosaand exchanges the top two double (32 bit) gusbers oa 
the stack. 
di OSWAP d2 
d2 dl 
ROT : This coeeand rotates the top J entries. Entry 3 goes to the top 


of the stack. The top entry is aoved to the 2nd entry. The 2nd 
entry goes to the 3rd entry. 


nl ROT a3 
n2 nl 
n3 n2 


CHAPTER 9 
MEMORY COMMANDS and MEMORY MANIPULATION 


FCS6H is an address containing the present aeaory size connected to the 
Sinclair. To display the aesory size type the following. 


HEX FCS6 @ DECIMAL . (ENTER) 
2048 OK (This is the seaory size of a systea with 2 KB of RAN.) 


MEH: This is a command which places the aeount of aeeory currently 
available to the syste onto the user stack. 


DECIMAL MEM . (ENTER) 
640 OK (This is the asount of available sesory for a 2 KB 
System on power up.) 


VLIST + This will display all the FORTH words presently found in gesor y. 


Sei This will put onto the user stack the current address of the user 
stack pointer. 


ALLOT : This coseand takes a nuaber froe the user stack and reserves 
that aany bytes in the dictionary. 


O VARIABLE Vi 22 ALLOT (ENTER) 

OK (Vi when entered now will put the low address of a 24 
byte block of RAN in the dictionary which could de used for arrays 
or character strings etc. 22 bytes were reserved by ALLOT and 7 
were reserved by VARIABLE to aake 24.) 


@ (STEP on the Sinclair): This fetches the value at the 1 location 
on the top of the stack. The value is placed on the stack. 


addr @ nt 
A practical example aight bes 
J0 +ORG @ 130 +ORG generates the address of the systee 


variable which contains the display buffer 
petit: The e gets the address of the beginning of the display 
buffer which is usually OFBOOH.) 


' (OR on the Sinclairds Stores the second stact entry in the eesory 
location specified by the top entry. 


addr ! -- 
Eradple : 


HEX 32 FD00 ' (ENTER) 
oK 


(This puts a R in the upper left hand 
corner of the display in a 32K or 
less systea.) 


Notes TREE-FORTH will not shield you froe storing values in dan erous 
areas (for exaaple the system variables), So be careful to store on y in 
_ free gest y. 


21 ao and prints the contents of the address on the top of the 
stack. 


addr ? -- (If Viisa variable 
4 ree print its coa- 


Vi ? (ENTER) 
00K 


+! : Increaents the contents of aesory havin the address on the top of 
the stack by the second i tes on lhe stack, ” 


addr -- 
A t 


Eranple. ; 
23 Vi +! (ENTER) (This will add 25 to the variable v!) 


C! : Stores a BYTE of information (8 bits) into the location specified 
by the address at the top of the stack. 


b addr C! 


Ce : Fetch one BYTE of inforeation (8 bits) fros the location described 
by the address on the top of the stack. 


addr Ce b 


COPY ¢ This copies one screen of inforaation (512 bytes) to the adéress 
on the top of the stack fros the address found as the second entry. 


addr! COPY --- 
addr2 


O VARTABLE SCRI 510 ALLOT FBUF SCRI COPY (ENTER) 


the editor screen into a eso y buffer SCRI. 
inforeation all you have to do is SCRI Fur COPY . 


MOVE : This comeand is used to eove blacks of dener y around the systes. 
It will take three nusbers froe the user stack. The first is the 
number of WORDS (2 bytes) you want to wove, the second is the 
destination address, the third is the source address. A routine 
which will do the sane thing as the exanple for the COPY above is: 


O VARIABLE SCRI 510 ALLOT FRUF.SCRI 256 NOVE (ENTER) me an 
e coateats 
of the editor screen and copies it to SCRI. 256 words is 512 bytes. 


FILL’: One would use this to fill areas of eesory with a specific 

character. The FILL coseand takes three nuebers iroa the eser 

» Stack. The first is the character which is to fill seaory, the 

second is the nusher of bytes m mant filled, and the third ls the 
address of the area you want filled. 


FBUF 512 14 FILL 


This will store 
the contents of 
To recall that 


Will fill the edit screen up with periods. 


24 


BLANKS : Is just lite FILL but it fills eeaory with 0’s and only uses 
two nuebers froe the user stack. The first off is the nuaber of 
bytes you want blanked out and the second is the address of that 
area. 


FRUF 512 BLANKS Will blank out the editor screen. 


FBUF : This is an INTEGER value which contains the base address of the 
display buffer. To access the display buffer all one needs to do 
is ty e FBUF and the address of the 15 buffer will de 
ry ed onto the user stack. To change FBUF 311 you need do is 
put the new display buffer address onto the stack and type 10 FBUF. 


b : Adds the nusber found on the user stack to the address of the 


n of the systea variables and is eost coeaonly used to 
access the system variables. 


Ds 917 a 32 dit ausber at the address found at the top of the 
stack. 


addr D! -- 
nlos 


nb i gh 


DO : Fetches 2 32 bit number found in the location whose address is on 
the top of the stack. 


addr de nh i gh 
nlow 


PAD : This places the address of a 44 byte scratch pad on the user 

stack. The soratch pad can be used for storage 1 the user. The 

PAD will build into other sections of the a i H language if 

ore than 64 bytes of it are used so be careful not to overwrite 
S area. 


CHAPTER 10 
DATA TYPES and VARIABLES 


10.1 DATA TYPES 


TREE-FORTH as 12 n realize by now operates on either 16 bit 
integers or 32 bit integers (double precision). There are operators for both 
types af nusders. Integers are one type of data while another type is aade up 
by characters. TREE-FORTH characters are standard ASCII characters and can 
be found in APPENDIX A, On sone git beat. point nusbers are in- 
cluded. due to lack of space TREE SYSTEMS is not able to put floating point 
arithsetic in the TREE-FORTH EPROM without an extension. 


In this chapter, the different types of data variables are er tei ned. 


10.2 VARTABLES 


VARIABLE : Is used to give a variable nase a specific address in the 
1 It then sets astde 2 bytes in the dictionary for the 
value of the variable. Anytiae the variable nase is used in FORTH, 
the address of that variable is placed on the user stack. The 
variable is always given its initial value when it is defined. 


value VARIABLE var nase 


value = a nuser it value to be assigned to the variable 
varnase z a character nase chosen by the prograneer, 


After the initial definition, any tise the varnaee is used it plates 
the address of the variable on the user stack. 


O VARIABLE AVG (ENTER) 

OK (0 is the initial value and AVG is the variable nase) 

AVG @ . (ENTER) 

0 OK (AVG places the address of AVG on the user stack, e gets 

the nusber which is stored in AVG and . prints il.) 
The user can also use a 2VAR for double nusder 3. 

4 oye dictionar ae for a 32 bit storage, 

dan will pu 

stack, 


This coesand creates a 
Using the variable that 2VAR 
he address of the first of the four bytes on the user 


10.3 INTEGERS 


INTEGER : This cossand is very auch like variable. It creates a 2 byte 
variable in the dictionary, but instead of placing the address of 
the varaible on the stack, it places the actual value. 


value INTEGER intnane 
14 INTEGER INTI (ENTER) 


(Here we have created an 
daitial value of 100.) 


integer variab’~ with an 


— —— Lu— Re 


TO : Changes the direction that the inforaation in an INTEGER tates. 
Anytiee an integer variable is queried its contents are placed on 
the stack unless that INTEGER is pieced by the 'TO coasand. 1“ 
1 bii m a 10 the integer wil) be loaded with data froa the 
stack instead. 


$= (A+B) 9C/100 in TREE-FORTH could be written as 
AB+e*C#100/T0S | if ABC ES are INTEGER variables 


To access an INTEGER it is only necessary to type the integer’s name and 
the value of that integer will be placed onto the stack. To change the 
variable you aust put the new nusber onto the user stack and type 10 intnage. 
These constructs can be placed inside definitions of course. 


10.4 ARRAYS 


Arrays cen be created in FORTH just as in BASIC, FORTRAN, or other 
languages. First, space aust be alloted in the dictionary. 
This will rene variable 


© VARIABLE VAL 22 ALLOT (ENTER) 
naned VAL. then it 


ives VAL an initial value of 0 and reserves 22 additional bytes 
or it in the dictionary, This gives VAL the capacity to hold 
twelve 16 bit nuabers, 


-To access ay 2 byte value in the array put the array itea you wish to 
access on the stack and use the following coneands, 
This will access the proper array value by 


20 VAL + @ (ENTER) 
doubling the index, adding it to the 
address, and fetching the proper nueber froe that address, 


This is not the path ar Pi construct arrays. A aore efficient and 
elegant way is to use the (BUILDS .. DOES) construct. This eethod will be 
ia the chapter on defining words. 


F 
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CHAPTER 11 
CONTROL STRUCTURES 


Note: Unlike other FORTH versions, TREE FORTH allows the user to use the 
IF ... ELSE ... THEN and the... DO... LOOP statements outside of a 
definition, That is, TREE FORTH allows you to generate headerless code which 
can be entered interactively in the execution screen. 


If.. ELSE ., THEN : This is a special compile set of words which can 
be used to sake logical branches. IF checks the ai entry on the 
stack. Jf the top stack entry is non-zero, the code between the IF 
and ELSE is executed, If the top entry is zero, the code between 
the ELSE and the THEN is executed. Exaaple : 


1 IF .° TRUE ° ELSE .° FALSE ° THEN (ENTER) 

TRUE OK (The statesent between If and ELSE is executed.) 

O IF .° TRUE ° ELSE . FALSE ° THEN (ENTER) 

FALSE OK (The statement between ELSE and THEN is executed.) 


Now try the following : 


GIF Li ¢. ELSE 22. THEM (ENTER) 
4 OK (The statement between ELSE and THEN is executed.) 


IF .. THEN: A siapler construct than the IF .. ELSE .. THEN is the IF 
+» code .. THEN construct. This stateeent allows the execution of 
code if the value on the stack is non-zero. An eraaple is: 


1 IF 1 1 +. THEN (ENTER) 
2 «K This displays the addition of 1 + 1, because the 
test is true or a non-zero value is on the stack 
before the IF. If the initial stack entry were zero the code would 
not be executed. 


DO .. LOOP : The DO LOOP uses the ta two indicies on the stack followed 
by executable code within the DO and LOOP words. 


lieit initial DO ., code .. LOOP 


liait = the me liait of the count for the loop 
initial = the low lieit of the count for the 100p. 


The 'inder l is incresented by one froe the initial value to one less 
than the lieit. The value of the inder is queried by the variable I. 4 an 
exaeple type in the following: 


9 0 DO 1. LOOP (ENTER) 
012345678 UN should be displayed. Mote that the upper 


liait 9 does not get executed. 


DO... +LOOP : This construct. allows the user to incresent or decresent 
the count by any value and it looks like this : 


liait initial DO stateaents incresent +LOOP 


lieit = is the upper or lower liait for the loop, 
initial © this is the value where the count is started. 
stateaents = any FORTH word or words. 

incresent © any positive or negative value. 


-3 0 DOT. -1 400 (ENTER) 
0 -1 -2 -3 -4 MK «(will be displayed) i 


LEAVE : This terminates the loop at the next LOOP or +LOOP. It 1d 
placed in an IF THEN clauses i could be 


For nested loops a second index is available, the index J. For further 
nested loops, the N index can be used. 


ONI corresponds to J 
l Ni corresponds te J 

NI would correspond to the next index and so on. 
Try : 10 0 D0 10 0 80198. LOOP CR LOOP (ENTER) 


CASE 1 The case statesent allows transfer to Bany places on the bases of 
an index, 


1 


CASE is sost often used in a definition, however it tan also be used 
interactively on the execution screen, The coaaand foraat follows ! 


CASE eb el e2 e3 el; 12 of sore statenents can be used) 


STACK VALUE EXECUTION PRIORITY EE 
l el 
2 ; e? 
3 e3 
ete. etc. 


SUMMARITED : The statesent at e0 is executed when the stack value 
eied E CASE has a value of 0, ef when the stack value is 1, etc. el aay 
bes definiton, or any aathesatical expression. To test a CASE type : 


2 3 (ENTER) 


(put the operatives on the stack) 
ox 

1 CASE 8 +3 . (ENTER) 
5 OK 


(this will execute the “, 2 + 3) 
(3 will be the result) 


DEGIN ., AGAIN: This statement will execute any code found between the 
BEGIN and AGAIN words. When AGAIN is reached control is transferred 
18 BEGIN and the code is executed again thus creating an leiste 
Oop. 


BEGIN .° HELLO ° CR AGAIN (ENTER) and will print out 
HELLO 


tte, mill Continue te be printed te the Botton of the 
ger en, And LABA ateak "eont nue by strat ting. 


i 3) 
$ 


BEGIN .. flag UNTIL : This stztesent continues to erecute the code 


found between BEGIN and UNTIL until the flag is true (non-zero). 


It looks like this: 
l] 
BEGIN statesents flag UNTIL 


stateaents = any FORTH word or words. 

flag =a logical operation which leaves a true or false value 
on the stack which is interpreted by UNTIL . If the flag is 
‘true, non-zero the loop is terainated, otherwise the 
execution is continued. Exaaple: s 


O BEGIN 1 + DUP DUP . 9 = UNTIL (ENTER) 
123456769 OK 


This routine takes the top stack value, incresents it 1 one, duplicates 
it twice in order to save the value before displaying, and then lt per for as 
the logical operation, a coeparison to 9. 


Wotice that in this case the 9 is printed out. This is done 
because the FORTH statesents are executed before the UNTIL checks 
the top value of the stack against the 9, 
BEGIN 5 WHILE .. REPEAT : The construction of this word is as follows: 
BEGIN words logical operation WHILE words REPEAT 
words = this can be N FORTH word or cosbination of words. 
logical operation = this is a logical operator which leaves 
either a true or a false value on the stack. Exaeple : 


BEGIN f+ DUP DUP . S > WHILE . END® REPEAT (ENTER) will display 
012345 6 END Ok 


ag 


CHAPTER 12 
CHARACTER INPUT OUTPUT 


12.1 CHARACTER STACK 
TREE-FORTH is unique in that it has both nusber and character stacks. 


The character stack stores bytes of ASCII code and provides a sor 
efficient and convenient sethod for 115 and ani pul zt ion than does singly 
a user nveber stack. The stack pointer for the character stack can be found 
in the systea variable located at address FCB4 H. Tree-Forth uses the IY 
register of the CPU to hold the user stack Kelter These stacks are inde- 
pendent of each other, but in order to sake use of the character handlin 
rotin ia 177 systea, character strings gust aaintain 3 en foraat 
character string consists of two parts: the string of ASCII characters that 
reside on the character stack whic sunl aake up the string, and a nuaber 
which sits on the user stack and is a count of how Bany characters that are 
stored in the character string on the character stack. Mani ulating charac- 
ter strings is done through manipulation of the nusbers on the user stack 
which represent the length of the character strings. For instance, to con- 
catinate two character strings into a single character string, all one needs 
to dois add the two nuabers on the user stack together to generate a nuaher 
ite r rants one composite character string. Or siaply put, a + concat- 

nates strings. 


4 


12.2 CHARACTER COMMANDS . 
STRING 1/0 


»" 2 Defines the beginning of a string of characters to be output to the 
screen. Any characters found between a .° and a ° will be placed 
into a character strin and output to the consel device (the execu- 
tion screen). For instances 


t WESS .* THIS IS A MESSAGE °; Will print THIS 1S A MESSAGE to 
the console each tiee MESS is 
encountered in a prograa or typed on the execution screen. 


°: This works just like. et instead of taking the character 
. String and outputting it to the console device, the ° will leave 
the character string on the character stack to either be manip- 
ulated by another routine or directed to another screen. The 
length of the sing will be found on the nueber stack jeeediately 
after ° is executed. The parser expects a space ianediately after 
the initial ° and does not count it as a character. Both . U and ° 

use the to sark the end of the input character string. Exaaple: 


. THIS IS A STRING ° When placed in a definition or in the 
execution screen will display string 


between the quotes. 


* THIS IS A STRING ° This will insert this string in the 

character buffer with the nuaber of 

characters in the string placed on the nuaber stack. (The parser 

pects apice after the initial ° and does not count this as 2 
character. 


E 


111 


eae ES 2 eae — —— —— — mE- 
nee: one he BR PAR 


E) 
| 


ABORT” : Checks a flag taken fros the user stack and if the flag is true 
(non-zero) then a user defined error aessage placed between the 
final ° in ABORT” and a tersinating ° is displayed and a ware 
Festart is executed. This comeand could be useful for displaying 
user defined error sessages in a pr ogf 28. 


o 
=. 
ee 


Is used to print a carriage return line feed on the screen. 


5 0 DO .° THIS IS A STRING ° CR LOOP (ENTER) would produce 
THIS 18 A STRING (count 0) 


THIS 18 A STRING (count 1) 
THIS IS A STRING (count 2 
THIS IS A STRING (count 3) 
we IS A STRING (count 4) 


SP : Will print a space to the console screen. 
CLS : Will clear the console screen. 


EMIT : This coesand is used to take an ASCII character froa the user 
stack and output it to the console screen, 


KEY : Calls a routine which will get a value froe the keyboard and put 
the ASCII value of that key onto the user stack. 


SE s This coseand gets a word fros the stack i with a space or 
(ENTER) and puts that token or string onto the character stack), 


This will take a character string and store it onto the address 
found above the character count of the string on the nuaber stack. 


° TWILL PUT THIS IN THE PAD pa W! „il put the string defined 

' by the quotes into the pad. 
After the string is transferred to the pad, what the aesory ieage 
looks like is a single byte character count followed by the charac- 
ter string. In other words, after sree ins the string above 
typis a PAD CO. will print out the nusber of characters in that 
string. (27 in this instance) ‘ 


W! 


Will take an address froe the user stack and fetch the character 
string stored at that address. It places the character string 
itself onto the character stack and the nusber of characters in the 
character string onto the user stack. 


PAD WE CO . 1 will piat the character string found in the 
pad out to the console device. 


e 
= 
— 


Allows output of a string to the console screen, editor screen, or 
any user defined screen. The coseand “noi to find the string on 
the character stack with the nusber of characters on the user slack 
and aust be preceeded by a valid screen identifier. 


On the execution screen enter the following: 


° THIS IS A STRING’ (ENTER) To display this to the console 
screen (the execution screen) 


CO . u (ENTER) To display this to the editor screen type: 
ED .W (ENTER) To utr the string to any other screen type: 
` screen identifier .W (ENTER) 


.C : This coseand follows the saee foreat as .W but it works like EMIT. 
It uses two nuebers froa the user stack, the first is the screen 
identifier, the second is the ASCII value of the character that you 
want to output to the identified screen. 


CN : This cosaand is just like .W sice! that it always directs it’s 
output to the console screen and it needs no screen identifier. 
CM will then take a character string and output it to the console. 
A. text ° is just likea ° tert ° .CN 


COROP ! This coseand word drops a character string off of the character 
stack. It assuees that the nusber of characters in the word is 
stored in typical fashion on the user stack. 


COUP 1 This comaand will duplicate a character string on the character 
stack auch like OUP duplicates a nuaber on the user stack. 


CO: Is used to take a character string froa the character stack and 
direct it to the keyboard input buffer just- as though that 
character string had been typed in on the keyboard. This is used 
for a variety o er one which cones to aind is the am 
self re-scheduling of tasts. A siaple eraaple of how .CO works ist 


pr * .CO (ENTER) 
VLIST etc. ox 


will take the character string 
VLIST and direct it to the key- 
board just as jf you typed it. 


12.3 CHARACTER STACK/MUMBER STACK OPERATIONS 


There are a group of cosaands in TREE-FORTH which use both the nuaber 


stack (or user stack) and the character stack. These coeeand types are 
described in this section. Resesber that a character String always consists 
af two things: a nueber on the user stack which describes the length of the 
character string (the 
string itself which resides on the character stack. 


er of characters in the string), and the character 


CoM: mis cossand resoves one character froe the character stack and 
places that character’s ASCII value onto the user stack. It will 
reduce the character count which is on the user stack by one and 
place the ASCII value of the character taken froa the character 
stack on top of the character count. If the character string is 
sort this routine will leave the null character count at zero and 
return a 0 ASCII value. 


WC: This does just the opposite of COW. It takes an ASCII character 
value off of the user stack and une it on the character stack. 
The character count for the character string that the ASCII 
character will be appended to, should be under the ASCII value on 
the user stack. The character count will be incresented by one to 
reflect the extra character on the character stack. 


u) 1 This, comand is used to foreat character strings for iene and 11 
pi ine A ee ating - épa tong à 
In EEROR e este yautemild Cae 


te Va) enacts 


11111IIIIIIIIII 


this siaply by the coeaand 8 1) This will take any character 
string of seven characters or less and append enough spaces to the 
1 of it to eate it eight characters long. T uses this 
to get all the words into coluans. A routine which will convert a 
nuaber on the user stack to a formated three character long charac- 
ter string and print it out could look something like this: 

: . f E 38) COW; If you use f instead of . all 
nuabers will be printed out in at least 3 
character long strings. 


: TBL CLS 11.1 DOM 1 DOT Is LOOP CR LOOP 


IN is a rout 
which will generate an a 


0 by 10 aultiplication table. 


H)A : Is useful when transforeing HEX nibbles into an ASCI! equivalent 
characters. HA takes a nuaber off of the user stack in the range 
0-15 deciaal and converts it into its appropriate ASCII equivalent 
and leaves the character on the user stack. A 3 HOA EMIT will 
echo a D onto the execution screen. 


ADH : Does just the opposite of HDA, it removes an ASCII character in 
the range 0-9, A-F and leaves on the user stack its HEE equal. 


| 


This is a routine which is used to attespt to convert characters in 
a character string to a nusber on the user stack, Let’s say that 
the character string which represents 100 is found on the character 
stack, Hf executing 201 the character string will be converted to 
a 16 bit integer with a value of 100 and it will be placed on the 
user stack. This coseand leaves a flag of f on the user stack above 
the converted nueber if the conversion is successful, otherwise the 
na will be a 0. If the conversion is unsuccessful the character 
string will de left unchanged and can be used to proept the user 
for a correct character rim: A routine which would use the full 
capabilities of this routine follows: 
1 READ BEGIN .° ? ° S@ 00 WHILE This routine will proest 
CR COW ° IS MOT 6000 TRY AGA the user for input with a 5 “ind 
IN ° REPEAT ; leave the input nuaber on the 
; stack if the conversion is good 
o otherwise it will print ont the original string and ask for further 
input until a good string is input. 


f : Does the opposite of >$, it reeoves a character froe the user stact 
and converts it into a character string in the current base. The 
dot. comaand uses @ and is defined as 1. 1 C0 1 . 


Ut: Is just like @ but perforas an unsigned conversion froa a 14 bit 
nuaber to a character string. U. is defined as 1 U. U C0. 1 


Dt: Is the double nueber version of . d. is then defined as: D. DI 


OW; . 


12.4 CHARACTER STRING COMPARISON 


iiz ù Expects two numbers fros the user stack, both should be addresses 
of character strings which are to be cospared character by charac- 
ter for epy. If the two strings which are pointed to are 
equal, a twill be placed on the user stack; if the two are not 
equal, a O will be placed on the stack, Both of the addresses will 
be resoved before the flag will be left. 


Takes an address off of the user stack which points to a string 
which is to be compared to the character string on the character 
stack. This is ouch lite We except here one of the character 
strings is on the character stack already. This routine reaoves 
the address but leaves the character string on the stacks intact 
before it leaves the flag. 


CHAPTER 13 
PRINTER COMMANDS 


Pt Toggles the printer on or off. If the printer routine is on, any 
information that goes to the video fay will also go to the 
printer, As an eraaple, to get a listing of all the FORTH words 
presently in the dictionary, type: 


P VLIST (ENTER) (This prints to both the printer and the console.) 


PRIR : PRIR to the printer device is as EMIT is to the console device. 
putting an ASCII value onto the user stack you can output that 
character to the piir by using PRIR, This works regardless of 
whether the P toggle is on or off. j} 


. 
v 
co 


This is written for the IX/Printer or any other compat ttle printer 
which is aade explicitly for the 15/1000 or 11/81. What it does is 
it looks for a character pune in the PAD which is 32 characters 
long or less, and print that lige out on the 11 /prister (or coe- 
atible printer such as the 15/2040 printer). The routine will pad 
he rest of an eapty line out with spaces and print one coaplete 
line out to the printer. It will not do anything with a user 
defined printer routine. 


* THIS IS A TEST ° PAD W! .P will print THIS ISA TEST out to your 
printer. 


PRINT + Is used when you-haye sose other ASCII cospatible dévice that 

' you want your printer output to be directed to rather than the 

I/Printer. The routine which you write to interface into oust 

»  resove the ASCII value froe off of the user stack and ese it to 

925910 to your printer device. As an eseple, let us say we have an 

RS-232 card attached to our syste and we have written two routines 

to interface into that card. One of thea is a routine which uill 

return only if the RS-232 card is ready te accept another character 

for output; let us call this routine RS READY, The other routine 

is siaply the routine which will place the address of the &S-232 

output port onto the stack, we will call this one RS ADDRESS. Now 

we can use these in the eee ganner te output characters 
through the RS-232 port instead of the defaulted 11 / br inter. 


1 RS OUT RS READY RS ADDRESS CA (This will output one character taten 
n oi 1 the user stack to the RS- 
port. 


PRINT RS_OUT (This reassigns the printer output to the routine RS_OUT 


instead of the default 11/fr inter routines.) 
I 


CHAPTER 14 
DEFINING WORDS 


FORTH is different froe any other languages in that it allows the user 
to define his/her own words to extend the language. Ide user can coapletely 
custoaize a set of words which can be or be used in any pf or a8. 


14.1 DEFINING WORDS 


This section explains how words are defined using FORTH, The basic 
construct 181 


1 wordnaee progran ș 


ia TREE-FORTH wordnase is cospiled into the dictionary as a word with a 
specific operation as defined after vor dnane and before the seai-colon. Try, 


1 AVG + 2 / (ENTER) 
OK 


Successfully 7 0 the above word will define a word which adds the top 
two stack entries and divides by two. In other words, AVG finds the average 
of two avebers, To execute this word type: 


2 4 AVG. (ENTER) 
3 MK 


The above statesent will put 2 on the stack, then ut 4 on the stack 
then execute the commands attached to AV6, and finally d spay the top stack 
entry left by AVG, We will next define a word that takes the average of two 
sets of avabers . using AVG and then check to see if the averages are equal. 
It will also print the appropriate response. 


1 EQUAL AVG ROT ROT AVG = IF 
„ EQUAL ° ELSE .° MOT EQUAL ° 
THEN 3 


The 2 ROT coseands here are included to put the value calculated by AV6 
" the bottoa of the stack and the next two nuabers to be averaged on the 
op. 


FORGET 1 You can forget say oort in the dictionary with FORGET if it is 


not protected by the FENCE value. Siaply type. 
FORGET token (ENTER) and token along with any dictionary 
entries coepiled after token will be 


resoved froa the dictionary. 
FENCE 1 You can protect any token fros Fuxb—T by typing: 
FEWCE word (ENTER) 


THRERHRRRREREREET 


14.2 : token .. (BUILDS .. DOES) .. 5 


This is one of the eost ispor tant constructs in FORTH. With it you can 
actually extend and expand the nuaber of defining words in the systes. The 
for aal coamand for this construct is: 


1 defining word (BUILDS definition code DOES) run tine code 5 


defining word = the nage you want to give to your coapiler. 
| definition code = the code which is executed when the defining 
word is used to create a new word. 
run tiae code = this code is executed when the new word is 
used as a coasand vor d. 


it is possible in a <BUILDS DOES) construct to have no definition code 

or run time code. An exaeples 
1 ARRAY (BUILDS 20 ALLOT DOES) ; Here is an exaeple of (BUILDS 
ee 8) construct with no ren 
tise code. This statesent will allow the user to create arrays of 
ten words (20 ALLOT sets aside twenty bytes in the dictionary, 
enough for ten variables). ARRAY is now a coapiling word which is a 
lot fixe VARIABLE except it reserves twenty bytes in the dictionary 
for user variables instead of just two and also uses ao initial- 
izer, An exaeple of how to use heray follows: . 


ARRAY NUMBER (ENTER) This creates an array called NUMBER 
which will reserve twenty bytes for 
nuaber storage in the dictionary. To access these twenty bytes ve 
need soe way to reference thea, perhaps by palcing the address of 
where they are found in sesory onto the stack. It just so happens 
that this is exactly what typing NUMBER will do for as. 

(ENTER) places the address of the first byte of the twenty bytes 
alloted to MUMBER onto the stack. 


The prograa can be expanded as shown below. We will create a one 
dieension array and allow the user to access any nueber in the array by 
placing an index on the stack. 


1 ARRAY! (BUILDS 40 ALLOT DOES) SWAP 28 + 3 


used will create a twenty word array. 
ARRAY! XYZ (ENTER) We have now created in the dictionary an 

array called IVI. We can insert a nueber, 
say 123, into the Lith word in this array by typing: 


123 11 XY2 ! (ENTER) What 


ARRAY] is now à 
coepiler which when 
Let’s aake one called IN. 


has happened up to this point? 
First, a 123 was placed on the nusber 
stack, Second, the index II was placed on the stack, and third, IV is 
encountered. III first places the address of aesory in the 1 where 
the aay is located and then initiates the execution of the code following 
DOES). n this case the top two entries on the stack are anpe (patting 
the index on the top and the address below it). Mert, we double the index 
with 21 because we are dealing with 16 bit values and address seaory 1a 8 bit 
bytes. The next thing we do is add the offset of the index to the address 
already on the stack. After this is done, the stack contains the address of 
the inate array aeaber and the value to be stored there. ” “Sore C) will 
Finally put the value iK the array. 


Y 2 
d a 


a 


Another routine could be written to fetch values fros the array and 
would look soaething like this: 


11 YYZ @ (ENTER) 


14.3 SYSTEM WORDS 


l.] 1 This word is used to suppress the execution of an ienediate 
aoe in a definition. The token which follows L } will, if ina 
definition, be cini to execute when the word being defined is 
executed and not during the definition of the word itself. 


( : Any words placed in parenthesis will not be coapiled and will act as 
cosaents in your prograe. Anything entered up toa’) ill be 
entered as a Coanent. 


» 3 Stores the 16 bit nueber found on the nusber stack into the dic- 
tionary at the gert available location. 


C, s This is like °, but stores a byte into the dictionary instead 
af a word (two bytes), 


HERE + This word places the address of the next free dictionary space 
onto the stack. 


— HERE addr 


H 1 This places the address of the senory location which contains the 
address of the next free dictionary space onto the stack. 


— H addr 


T: Places the address of the aesory location which contains the tail 
pointer of the dictionary onto the user stack. 


HEAD: Is used in eesti new cospi lers. Head creates the header of a 
dictionary word and links it into the dictionary. HEAD generates 
no code field and thus if a token is created with HEAD and no 
atteapt is eade to place behind it a code field, execution of that 
token will crash the systes. 


IMM: When jebedded in a definition, IMM gates that token an jeaediate 
aperi and that token will execute in the siddle of a definition. 
IMA is used to custosize coapiler words which generate code or 
fodify the dictionary without creating a header. 


” t Atteapts to find the word following the character in the dic- 
tionary, When found, the address is placed on the stack. 
” WS. (ENTER) The aachine code which sakes up M? starts 
2816 OK as 2816 in aenory. ~ The is a SHIFT/D on 
your systea. i 


i i f , 


CHAPTER 15 
TIME 


dade ia as you are no doubt aes are very useful and versatile 
tools which can do a surprising nuaber of hings. If you have been around 
some people who do not know a great deal about these tools, you aay have been 
asked: "What can your coaputer really do? Can it cool dinner or vacuue the 
carpet? What good is it if all you can do is stare at it“ And these are 
gone questions, what poo is a coaputer if all you can do is stare at it? 
Mell, of course it can help with Tyee the checkbook, organizing business 
inforaation, generating ailing lists, ca culating taxes 5615 out checks, 
and any nuaber of other mina, but there are a whole lot of t ings that a 
coaputer really can not do well because coaputers, at least in there sieplest 
eee do not have eyes, hands, and or a sense of tise. In short, 
computers can not be told to do what humans can do because they do not have 
the receptors and manipulators that we as hueans have. Most saal! coaputer 
systeas also lack the ability to keep track of tise, 

It is possible to give your 15/1000 12 30e “sensory” devices or 
transducers which would enable it to, ina lisited way prenn soae things 
in its environaent by attaching to it input ports or My convertors ett. 
You could also jie it hands, so to speak, by attaching to it output ports 
which could control sosething in its environsent. 


After having given your coaputer these tins it would still be aeces- 
sary to give it a sense of tiae in order to link it to the way that the real 
wordd does things. for instance, if you were collecting data in your house 
by aonitoring he teaperature and using that inforsation to better coatro! 
you furnace, your coaputer would, in all probability because of its speed, 
ave the ability to take a teaper ature reading once every 1/1000 of a second. 
Now it is obvious that gathering this auch inforsation would be useless and 
wasteful, but if you had a aethod of restricting the data-gathering process 
to read a teaperature once a ainute, the data you collected could be analyzed 
aore rationally and the whole project could be given a sense of orderliness. 


The easiest way to give 2 cosputer a sense of tine 18 to give it a clock 
that it can look at every tise re tell it to and so enable it to sate 
decisions about what to do and when to do it. Tree-Forth has just such a 
Clock, It is ade up of a systea variable that is increaeated every 1/60th 
of a second and counts {roe zero up to a lisit that can be set to anything 
from 1/ th of a second to over two years. Both the clock itself (the systea 
variable that is incremented) and the period (the changable lieit) are eade 
up of 32 bit integers which can be accessed by the two words: 


I 

TIME : WiN race ihe address of the systee variable which act as the 
easter clock for the syste. This variable is a 32 dit integer 
value which is increeented each clock tick (1/60th a second) and 
continues until it reaches the lisit set by the systea variable 
accessed by PER. Upon power up, this variable will default to 
zero. 


PER : Will place the address of the first byte of the 32 bit syste 
variable which is used as the limiting value to which the systea 
Clock counts. It is through this variable that the systea clock is 
given its overall period. This variable defaults to a count which 
represents 24 hours, one day. 


ww 


Two erzeples of how to use the clock are given here. The SET routine 
an ilies you to set the clock and the RTIME will enable you to display the 
de of day. ` 


t READ BEGIN .° 2° S@ 0 WHILE 
13 ENIT . CA AGAIN i 

: SET .” HOUR READ TH .° MIN® 
READ TM .° SEC* READ TS De D+ 
TIME BD! .° DONE” i 

1 RO 60. D/ SWAP DROP ROT ROT ; 


The READ routine is used to 
input one nuaber to the stack 
auch lite 3 READ would be used 
in basic. The .° ?° outputs a 
proapt to the screen. The S@ 
reads a token, in froa the input 


: CPT TIME de RD RD RD SWAP buffer, and the > atteapts a 
DROP ; conversion, If it converts OK, 
3 COL € COM DROP 2 U) 4 control will pass out of the 


s RTIME CPT COL Cow DROP CH 
COL CN COL 


READ routine and return with a 
„CM DROP 

2 TIME BIS CLS BEGIN 13 ENIT 

RTINE RGAIN 3 


valid nusber on the stack. If 
not the 13 EMIT .CN will return 
repeat the token, and outpu 
another proapt for another try. 
The SET routine poti tor input with an HOUR? and after a auaber l 
input it runs TH which aultiplies the 16 bit nuaber on the stack by the 
nusber of ticks in an hour and leaves the result as a double nusber on the 
stack. The sage is done for minutes and seconds leaving three double nuabers 
on the stack which are then added together with the D+ s and deposited in the 
paier clock with the TINE O! . Affer it is all done it tells you by saying 


The RO routine reduces a double nuaber by 4 it by 60. It leaves 
the -double quotient on the top of the stack and a 16 bit remainder under it. 
The CPT routine gets the 32 bit tise fros the easter clock and runs it 
through the RD prograna to leave the ticks, seconds, and ainutes on the stack. 
It then reduces what is left, the hours, to a single nuaber, so CPT reduces 
the tine to hours, ainutes, seconds, and ticks on the stack. COL converts a 
musber to a character string three characters long with a colon in the first 
location. RTINE puts the other routines together and displays the tiee in 
the foraat HH:MM:SS to the console. TINE DIS just displays the tiae over and 
over in an infinite loop, 


2 


* 
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CHAPTER 16 
TASKING 


TREE-FORTH is different froe sost other seall systes operaties systees 
in that it allows the user to task „ Tasking is the act of sched- 
uling a program to execute at sose tiee in the future. Any prograe can be 
scheduled in a task. The tasking coesands are given below in the order of 
use in defining tasks to run. 


Note: In TREE-FORTH you can run „ ten tasks sisultaneously 
in the background before the systee will slow down so auch as to be useless 
in editing new progr 283. (Tasks use valuable processor tise which is usually 
spent in editing new pr ogr 285). 


Tasks are set up in this way: 
TASK tasknage prograenaee where prograsnaae is any pr oer 28 
which exists in the dictionary 


and tasknase becoses the naee associated with the task you are 
defining. 


Note that at this tine the task has not yet been scheduled to run, it 
has only been defined. 


SCHEDULING TASKS 


The user can schedule a tast to run using the In, 
The tiae used can be: 


TT Task Vicks (1/60th sec). 
T8 Task seconds. 

TH Task ainutes. 

TH Task hours. 

TD Task days. 

I Task weeks. 

IV Task years. 


IN s Task identifier used to schedule a task to execute after the 
specified tiese has elapsed. 


EVERY, AT coesands. 


EVERY 1 This is a task identifier used by the task scheduler to schedule 
a task to execute repetitively using the period specified. 


AT s Task identifier used in conjunction with the systes clock to 
calculate the tiae existing between the current tine and the tiee 
specified during scheduling so that the task will execute IN the 
appropriate tiae. 


START : This identifier directs the task scheduler to clear the task 
overflow flag, the task execution flag, and the task execution que 
to allow'schedul ing to continue. 


STOP : Will set the task schedule overflow bit which in effect stops the 
tasks execution and scheduling. 


RUN : Will increment the task execution que if the overflow bit has aot 
been set, The net effect is to schedule the task to evecete the 


next clock tick if no other higher priority task is e ‘ting. 


—— — —aU— 4 


The foraat for scheduling is: 
cossand nuaber tise-type tasknase 


TASK prograaname TASKI 
EVERY 5 1S TASKI 


This schedules the task TASKI to run every 5 seconds. 


IN 10 TM TASKI This schedules the task TASK! to run in ten 
ainutes. So, now the task is scheduled to run 
ory five seconds after ten ainutes. The systea will automatically 


start scheduling this task upon the execution of this cossand. 


fore of this cosaand is: 
STOP tasknase (ENTER) i 


To tersinate the execution of a task the STOP coamand can be used. The 


To restart a task you aust reschedule it, or if it has already been 
scheduled you can use the START comaand. 

Tasks may also be forgotten just as ny other FORTH word. This is 
ossible because every task is a coaponent in the dictionary. So alternately 
ORGET tasknaee (ENTER) could be used to stop the task as well, however, the 

task cannot be rescheduled after this cosaand because the task would no 
longer exists in the dictionary. 


TREE-FORTH also allows a task to be run without scheduling it. This 
would be very helpful in debugging a task to insure that it is running 
properly. The cosaand is: 


RUN tasknaae (ENTER) 


The next command to analyze is START, but this needs some background 
inforeation, What should happen if your task was extremely long? That is, 
the task took longer to run than one second and the task was scheduled to 
execute every second. In a case like this the task would be rescheduled 
before it was coepleted. 


This can nappen in TREE-FORTH however, if your task were so slow that it 
cont ioualty rescheduled tasks before the previous one vas finished, the 
systes would finally lock up. A single task can be “back scheduled“ 63 tiees 
before the systes will lock up. This is all aore al explained in the 
technical reference manual in Appendix C at the end of this book. 


Now back to START. : START clears the task repis of "back scheduled” 
tasks and will unlock a locked up task. This is done for one task at a tine 
and the comeand for aat is: 

START tasknase (ENTER) 


Finally, two aore task coaaands. 


hy 
5 


} 


LOCK : prevents all tasks from running. Tasks are still being scheduled 
to execute arin a LOCK condition, but whatever pro rae is being 
executed when lock is executed will gain second to highest priorit 
in the system (second only to the master 1/4 second task) and vill 
not be interrupted by any other task. 


UNLOCK : allows tasks which have been LOCKED out to begin executing. 


LOCK should be run only for a short period of tiae. This comeand locks 
all lower priority tasks froe ponin If the LOCK to UNLOCK time was longer 
than the tise the lower e task was scheduled to execute in, then the 
lower priority task would be qued-up. LOCK does not ates the scheduling of 
tasks to be run, it only stops their actual execution. herefore, the pos- 
sibility exists for a task to completely fill it’s que buffer (63 scheduled 
executions). Upon UNLOCKing the tasks, the task with the overflowed que 
would be blocked froe running and could only be released by a START. 


TOFF : This comsand resets a systea flag so that upon the execution of a 
WARM restart the following iteas occur: 


7 Causes a LOCK of all tasks 
- Sets the background task to a null task. 
- Forces display to SLOW sode. 


4 
TON : Disables TOFF and allows scheduled tasks to execute after a WARM 
restart, 


It is also possible to link in a short 15 rae to run continuously in 
the background. A prograe linked into the background will execute any tise 
that there is nothing else going on in the systee and in effect has the 
lowest priority of any prograa in the systea. Progr 203 which are put into 
the background @ust not output any information to the console or request any 
information froa the keyboard input buffer. If a background task does, there 
is a high likelihood that the systee will not function properly. Background 
routines can schedule higher priority tasks to run and can access any of the 
system variables just as other routines in the system can, but the background 
routine aust execute quickly, in the order of 1/10 of a second or less, or 
the systeas overall performance will deteriorate. 


BACK : i used to link in 2 user routine into the background. BACK toten 
will sake token part of the background activity. 


NUL : Is a program which does nothing. It is used to swap out non-eapt 
tasks froe the background. BACK NUL will put the default nul tas 
into the background. 


Try this: 

2 A . THIS IS A TEST ° CR; This prograe will take A, a pr rae 
TASK BA which prints out the line “THIS 18 A 
: C RUN B; i TEST" and attach a task ° B° to it. 
BACK C The progras C, when executed, sche- 


; dules B to execute ee, C is 
then E into the background so that any tise the systes is doing nothing it 
schedules it to do something, namely execute A. To stop the sessage froe 
printing continuously to the screen just hit SHIFT/SPACE eomentarily. This 
n execute a WARM reset which autosatically resets the background task to 
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CHAPTER 17 
CODE COMPILER ' 


This section describes how machine code can be coapiled. The advantages 
of writing in machine code are a decreased meeory space used and increased 
execution speeds. 


Machine code is a tera referring to the type of nuabers the 780 aicro- 
processor inside the SINCLAIR will recognize. In poet it will only see 
coabinations of 0’s and 1˙8 iH into data and operation codes. It will 
be easier if we deal in the HEXADECIMAL representation of those nuabers. Now 
it would be iapossible to resesber what ate HEX nuaber did inside of the 
180 sicroprocessor. Therefore, each coaaand is represented by a nmemonic or 
a syabol. It is coason practice to write source code in these naeaonics and 
then convert the neenonic to the proper HEY nusber. TREE SYSTEMS has aade a 
special arrangeaent with the IIb Corporation (the aanufacturers of the 780 
alcroprocessor) to include a popes Reference Guide with the docusen- 
tation for TREE FORTH. This will give you a sieple source for the machine 
code conversions. 


First, the CODE coepiler will be described, and then an exaaple of its 
use will be given. The CODE compiler has the following fora: 


CODE .. hex code .. 3C 


The above shows the CODE cospi ler outside of a definition. It could 
also be used inside of a colon definition, The CODE coepiler places code at 
the current head pointer in the dictionary. Inside of a definition you can 
have ae many words as you want before CODE and after the ;C. Here is an 
exaeples } 


A sachine code routine can be written to add the three nusbers found on 
the user stack and put the result on the stack. We will use the HL and DE 
registers for this, but first a little background. 

TREE-FORTH supports commands for putting nusbers onto the user stack and 
reeoving nuabers froa the user stack. To resove a nuaber fros the stack all 
you have to do is execute a restart 2 op code (HEX machine code 07). This 
coesand takes the nuaber off the user stack and places it into the HL 
cote pair. Froa there can use it in a machine level CODE progran, To 
take a nuaber froa the HL register and load it to the user stack you aust 
erecute a restart one op code (HEX CF). Now let's write the routine, Ide 
consents to the right of the seai-colon describe the logical order of events. 


ES PUSH HL ; This saves the contents of the HL 
DS = PUSH DE 3 and DE by placing thea on the 

} processor stack. 
D7 OUP OP 3 takes the top stack entry and 


t 8 it in 
EB EY bk, ; this exchanges the contents of 
y the WL and DE registers ' 
07 bpOf 3 takes the 2nd stack entry and 
3 places in the ML register 
19 ADD M, bk ; this adds the contents of HL and 
puts the result in Hls ‘ 


FR FLA hove anewor of Hest addition 


11IIIIIIIIIIIII 


to DE 
ets the third nueber 


D7 f OP 
19 ADD Hl, ot s Adds the third nuaber with the 
; sus of the first two. 
CF  UPUSH í puts the final result back on 
3 the user stack. 
DI POP DE ; 
E1 POP HL : ; Restores the HL and DE registers 


No return op code is necessary, it is automatically inserted by the 
outer interpreter or the“; at the end of a colon definition. 


Now, to enter this code in the dictionary under the comeand word 3+ the 
correct prograseing statement would be: 


: J+ CODE ES DS 07 EB D7 19 EB D7 19 CF EI DI C; 

To execute 3+ place 3 nuebers on the stack and use the new cossand. 
123 3+ . (ENTER) 

b OK 


3+ adds the three nusbers and outputs the sua, 6, on the stack. °.’ 
prints the top stack entry. 


` N 


CHAPTER 18 
APPLICATIONS PROGRAMS 


One of the first prograas you will want to oy on TREE-FORTH is a task 
which will continually display the user stack on the bottoe of the console 
screen. The commands are given below. 


The entire progras should be typed on the editor screen. Then switch to 
the console screen and type CPL to compile the entire editor screen. 


— top of editor -- HEY CLS 16 C0 5 +C! 
017 ff 17 SCREEN ST ST REV 
: SCL O CNC ST .W; 
1 STD ASW ST ; 
1 514.4000 4 - PicK STD Loop 


: STE SCL ST4 FATE SP@ - 2/ . ST 
= ST W STD: 
TASK STK STE EVERY 2 18 STK 


What is e The first line clears the console screen. The 
second line creates the reverse video display line at the bottoe of the 
screen, Ide screen name is ST (for stack screen). The SCL word is a screen 
Clear comsand. STD is a screen display coanand, NE ST4 is the word 
which i the top 4 stack values, STE, stands for Stack Execute. This 
is the execution portion of the code. The routine clears the screen (SCL), 
then displays the ier 4 entries (ST4), then gets the stack pointer value and 
displays that value to the stack screen (ST), Finally, the last statesent is 
a task which schedules the program called STE as a task called STK. The task 
is scheduled to run every 2 seconds. 


Following is another little routine S gay want to use. This does the 
same thing as a READ AS statement in BASIC. 


t READ .* INPUT REQUEST ° Se; 
To display the result type: 
CO .W (ENTER) 


Here is a prograa which converts Fahrenheit degrees to Celsius. 
let us read in a variable: 


: READ .° 2° Se; 


U 
This gets a ete ing from the keyboard 
and places it on, the character stack. 


First, 


This will display a proept 62] and get a word 
froa the user. Next, we can write the word to 
U 


convert the input to a nueber. 

2 INPUT READ >@ ; > converts the top of the character stack to 

a aber. We aust drop a character because the 

Conversion leaves a 1 or a0 depending on whether or not the 

conversion is successful. Wert, let us write the actual conversion 
Calculation. 
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: CEL 32 - 100 1 / 5 1 100 /; Note that the value aust be scaled 
before perforaing the 


b 
division. A later division by 100 is needed to ring the result 
back to its orginal scale, Next, we will write a routine which 
will give us a printout in a nice forsat. 
: PRINT .° CELSIUS DEGREES * , ; uly, here is the progran word 
which ties all the others together: 


: CELS INPUT CEL PRINT ; 


definition 
stack), 


t 
ANOTHER PROGRAM, A PROGRAM TO CALCULATE STRAIGHT-LINE DEPRECIATION. 
We will aodify the read statement fros last tiee: 
: READ2 . ? 8e ) DROP ; 
0 VARIABLE ANT 


O VARIABLE YEARS 
O VARTALBE LAND 


Now that we have the variable nases, let us continue with the input 
statements: 


Note that we could also test each 
i word individually by t ing each 
(making sure that there is an appropriate value on the 


: INA .° ENTER THE PURCHASE VALUE ° READ ANT ! H 
: INY .° ENTER THE NUMBER OF YEARS ° READ YEARS ! ; 
: IM. ENTER LAND VALUE ° READ LAND ' : 


„ Now the land value will be subtracted froa the property value and the 
difference will be divided by the nusber of years to find the depreciation, 


: DEP ANT e LAND e - 100 t YEARS e / 100 /; 


si Now let us print the result and arrange all the words into one cossand 
word, 


t PRINT .* STRAIGHT LINE DEPRECIATION: "°. } 
+ PRODEP INA INY INL DEP PRINT ; 


ahne editing and cospiling this progras, you can execute it by typing 


* 


tej 


APPENDIX A 
ASCII! CONVERSION TABLE IN HEX AND DECIMAL 


Mote that the 1 listing includes all of the ASCII characters and 
their nusber equivalent. The SINCLAIR 2181 / TS 1000 in the FORTH eode will 
support all of the ASCII characters excluding lower case. Because TREE-FORTH 
ospite y replaces the basic ROM operating system all of the characters have 
been redefined to the exclusion of all graphics characters. 


ASCII CHARACTER SET 


HEX DECIMAL CHAR HEX. DECIMAL CHAR 
00 oo NUL ' * 38 1 
1 ol SoH 127 37 ' 
02 02 511 1 B 41 ( 
03 03 ETI 1 2 11 ) 
% 04 EOT 1 A 4 1 
05 05 ENO 1298 6 + 
06 005 ACK 1K 44 ' 
a 07 BEL 1 20 45 $ 
08 00 BS + Æ 4b 
0 00 HT 1 F 17 
04 10 LF 1 30 48 0 
59 11 VT 1 1 49 l 
00 12 FF 1 32 5 2 
00 13 CR 183 31 3 
of n 50 111 32 4 
oF 13 51 1 35 53 5 
10 10 DLE 1 3 84 b 
11 17 bel 1 37 33 7 
12 19 dez 1 3B 356 8 
11 17 OC} 1 39 37 9 
11 20 Oca 1 JM 5 : 
15 21 NAK 1 3 59 j 
18 22 SYN : 3 60 t 
7 B ETB 1 JD bf 2 
8 20 CAN 1 3 62 ) 
19 23 EN 1 If 63 7 
11 28 SUB 1 40 64 ê 
1B 77 ESC 1 M 35 A 
10 29 FS O R2 b B 
1D 29 6S 1 B 57 £ 
1E 30 RS ' A 68 D 
iF 31 1 45 839 E 
20 32 SP + 48 70 F 
21 33 ' fae! nee 
22 1 ‘ 1 B 72 H 
23 3 $ B | 3 I 
4 30 $ 1 A Ñ J 
23 y 1 1 | 75 K 
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APPENDIX B 
ERROR CODES 


The following is a listing of error codes, These will appear in the 


ERROR letter 


An error message will appear whenever the operating systea deturaines 
that either a catastrophic error has occured or the user has made a 
pr ogr ansing error. 


ERROR F 


TERROR H 


ERROR N 


ERROR R 


ERROR S 


SERROR U 


This error message is displayed when the user atteapts to 
forget a fenced word, If the fenced word appears anywhere in 
the list of words being forgotten this error will be displayed. 


This error e will de ace if the user atteapts 
to enter a token which cannot be interpreted as a hexadecisal 
nuaber or is not found in the dictionary. 


This error sessage is displayed when the available usable 
neaory ( RAM) is almost full. An error M will occur when the 
user progras area runs to within 32 bytes of the user stack. 


Error R stands for redundant. If the user trys to define 
a word with a nase which elong toà Peoria already in the 
dictionary, an error R will be tagged.” The word or task you 
are defining will still be defined but will have priority 
over the previous word in the dictionary and the word or tas 


already defined will no longer be accessable to the progr asser. 


This eessage is displayed if the user stack pointer 
underflows, something which should never happen since poping 
undefined information off of the stack is a no no, 


Error U stands for Undefined Word. This eessage is 
displayed when a word is used in a definition and either does 
not convert properly into a nueber or is not found in the 
dictionary. ( This is only followed by a ware reset if it 
occures in the aiddle of a definition. ) . 


8 NOTE : These errors will generate a wara reset after there display. 
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APPENDIX C 
TECHNICAL REFERENCE 


The technical reference is in progress 
and will be sent on request, 


Ponp = AT 


| 
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INDEX of COMMANDS i Coaparison Operators 


Arithaetic Operators Arithaetic (8, 16, and 32 bit) 


Single Precision (16 bit) pm C= 30 dude EF Is bi = b2 2 f21 yes, f=0 no. 
ae z Jo inet f Is nl = n2 ? $21 yes, #20 no. 
Oper ator Page Function Description ( 20 ont nd E f Is nl 2 ? fz1 yes, #20 no. 
ö ) 2) 91 2 Ef Is nl > n2 ? f=1 yes, #=0 no. 
' 25 nl n2En3 n3 enten2, i 9 a k Isn = 0? fel yes, $20 no 
- 25 onl n2E n3 n3 =nl-n2. 00 V on — ¢ Isn¢ 0? f⸗I yes, #=0 no. 
t 2 ni n2En3 n3 tn . 0) 30 nEf Is 00 0 7 f=! yes, £20 no. 
/ 20 onl a2 b n3 n3 1/52. ud Sink m2 EF Unsigned 4. 
21 2b alk az n2 112. ae D= 30 di d2 E Is dl z d2 7 f=1 yes, 0 no, 
2/ 28 al E n2 n2 2102, be 30 d d2 E Is di (02 ? f=1 yes, 20 no. 
us 2 ni 2 E n n3 =nftn2, Unsigned. D) 30 01 df f Is di > d2 2 =1 yes, f=0 no. 
17 28 al n n Eng n4 017023, bo⸗ W dEf Is 60. ? f=1 yes, else #20, 
NOD 280 al n2 k n3 n3 is the remainder of 51/52. 
/#00 27 al n2 E n3 n n3 quotient, ad remainder 1/52. Character String Comparing 
1/09 27 an ns Ens a quo, nS fes =(nttn2)/n3. 
MIN 2b al 2 E n3 n3 is ginieua of nl and n2. S= 4b c ad kf . Compares (addr) to c. fit. 
MAL 20 nk 2 E n n3 is aaxiaua of ni and n2. We 40 addr! addr2 E f Coapares two strings, at addr. 
11855 a 1 : n ae 198 value of nl. Em 
ni EN egates ni. Stack Manipulation 
t- 20 MEN Applies sign of n2 to nt. i f 
8 N User, Number Stack 
Double Precision (32 bit) ee 
DROP 32 nk Drops the top stack value. 
D+ 28 dl dz E d3 d3 =dl+d2, DUP J nEnn Duplicates the top stack value, 
D- 28 di d2 k d3 ‘d3 1-02. DUP 32 onfEnn Duplicates n only if 000. 
Dt 27 dl d2 k da d3 sd 1102. SWAP 33 onl m2 E n2 nt Swaps top two stack values. 
0 / 27 d 2 k d3 da d3 quotient, då remainder =d1/d2. OVER 33 al m2 Enin2 nt Gets 2nd stack value and copies. 
ONIN 30 dl d E d3 d3 is the unsigned ain of dl, 02. ROT I3 nl b as En2n3 nl Rotates 3rd stack value to top. 
DNAX 30 1 02 E d3 d3 is the unsigned max of d, 02. 2DROP 32 df E -- Drops a double @ froe stack. 
DABS 28 dl E d2 d2 is the absolute val of di. DSWAP 33 df d2 E d2 81 vars double nusbers on stack. 
DMINUS 28 ant 2 d2 is the negative of di. E PICK 35 ont E a2 Picks nith value of stack n2. 
SPe@ 34 — E addr Fetches addr of top of stack. 
Mixed Precision (16, 32, and 64 bit unsigned) 
Character Stack 
nt 27 uno k d d 1102. : i 
/ 27 dal E ge n3 n2 „ n3 reaainder d /n. Chur c Ecce Duplicates character string. 
NDS 27 di d2 k q 2d10d2. CDROP 4c CE -- Drops character string. 
MD/ 27 q di E d? d3 2 quotient, d3 remainder =q/d1. 42 fc Places chr string on chr stack. 
UnoD 28 ni En? n2 reaainder =d/ni. W) 44 ch n Ec2 Pads out cl to length n with sp. 
U/MuD 28 od al E ne n3 n2 quotient, n3 remainder /. fal 
Meaory Manipulation 
Logical (16 bit) i ' 
Nuaber Operators 
AND 29 nin2En3 Bitwise logical and of ni, n2. ` 
OR 2) al n2 E a3 Bitwise logical or of nf, n2. ce 35 addr Eb Fetches byte d froe addr. 
XOR 29 ol n2 k ns Bitwise logical xor of nl, n2. | C! 35 d addr E -- Stores byte b to addr. 
e U addrEn Fetches n froe addr. 
1 34  naddr 5 -= aes K to 11980 S 
i i . i k after. +! 35 sn addr k -- s n to contents of addr. 
Guide to Function Syabols Stack before Execution Stack a ii sadder Fetches double vord d froe ddr. 
b,b1,b2 t= Lower B bits of n. a : ASCII character. 0! 360d addr E Stores double word d to aie 4 
nni n2, etc. : 16 bit integers. addr := Meeory address. FILL 35 addr nl n2 E Fills nl bytes fro addr 95 . 
9,01, 62, etc. = 32 bit integers. f t= Flag, true 000, false=0. COPY 35 ddr! addr2 E -- = Moves 512 bytes froe al to a2. oa 
* 64 bit integer. E t= Execution of token, MOVE 35 addr! addr? n E -- Moves n words from addr! to addr2. 
c. cl. c t= Character ii =- te No operands on stack. BLANKS 36 addr n € -- Fills gerory with n Os at addr. 
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CLS 43 — k -- Clears console screen. : 
Character Operators t 2 4 42 — E -- Prints chr string to console, 7 
we A3 addr Ec Fetches chr string fros addr. ae i 
W! 43 c addr E -- Stores chr, strin e at addr, „ Sereen Generation: ang Dutput 
ae ; : SCREEN 18 ni! n2 n3 n4 E token Creates screen token in bndries. 
Definition Cospilers 7855 . C 0 a ade 3 -- 7915 cnt ris baad screen, 
; E ni bi ; W ä c addr È -- rites chr string to screen. 
: H = : z ae et ED 18 — E addr Places identifier for editor. 
bone 8 HEY a neee ele 00 19 — E addr Places identifier for console. 
a H = í -- e „ i pn REV 18 addr k- Toggles rev vidio on/off, 
eo E ss efining word generator. 
DOES) 49) es Eee BUILDS deconp/ ler. et en 
KEY 1 --E a bets next chr fros input buf, 
Integers and Variables 82 S -Ece Fetches toten froe input buf, 
VARIABLE z) n VARIABLE token Makes token a variable, Ini tg. EA k TERS PARSER strang Wo- SOL Bef 
WAR 37 d 2VAR token Makes token a double variable. Conversion 
INTEGER 30 n ee, token Kene Ar i ae ‘4 
— E — ets direction flag for ‘ a i i ble. 
PAD 36 — f addr Puts address of PAB on stack. Ea oo a: dees Gir ee a a a 
HDA 45 nEa Turns @ (0-15) into ASCII chr. 
Bases 00 9 J E 15 j „ . af val. 
i claEc ppends chr to string. 
19 5 15 n : — a erat a 18 1 Int pz La 3 c! : (2 2 reals 15 racler tron string. 
FEEST $ . n c onverts nuaber to chr string. 
DECIMAL 32 — E-- Sets current base to 10. Di 5 dee Converts double f to chr 517706 
ue 5 nEc Converts unsigned 1 to chr str. 
Controll Structures Ea I 45 c. En. Converts chr str to 8, #21 if OK, 
BEGIN .. AGAIN 40 -- E -- Infinite loop, code .. executed. Cassette 1/0 
BEGIN .. UNTIL 41 f b -- Flag before DATIL, loop if #20. ; 
BEGIN .. WHILE ae B = Exit loop from WHILE if 400. LOAD 20 n E-- LOADs cassette page n to (BLK), 
.. REPEAT 41 f E -- f lies before WHILE p STORE 20 n E-- STORES (BLK) to cassette as n. 
40 n E-- Branch to case arguaents froe 0. --) 21 — k -- LOADs next consecutive page. 
DO .. LOOP 39 nl n2 € -- Looping frpa n2 to nl step 1. (=a 214 — E -- STORES next consecutive page. 
DO .. +LOOP 39 nt n2 E= Loop froe n2 to ni step n3 +LO0P. $ BLK 21 — Eon Accesses block nuaber. Int 
IF .. ELSE FE If 00 code after IF executes. E t PAGE 21 — En Accesses page nusber. Int 
eo THEN 39 If f=0, after ELSE executes. CON 20 — E-- Turns auto coepile flag on. 
IF .. THEN NI tE- Executes ., if f is true (00). ii COFF 20 — 8 — Turns auto cospile flag off. 
I 40 --E n Retrieves index of DO (+)LO0P. 
1 40 --E n bets the second 00’s index. Printer Output and Control 
NI 40 nl E n2 Gets the nith nested 00's index. 7 
LEAVE 40 -- k — Exits DO LOOP or DO +LOOP. PRINT 47 PRINT token Links in user defined print rta. 
ABORT" 43 f E-- Abort and wara reset if f true. P 47 — E -- 11 N on or off printer. 
PRIR 47 a E-- EMITs ASCII chr to printer. 
Input and Output ER P 4 — k — Transfers string ia PAD to pe tr. 
Console Output Tise and the Systes Clock 
. 32. p ES Prints nusber to console. TIME 51 tk addr Gets address of clock count. 
D. 32 d E-- Prints double nuaber to console. Ea PER 51 — E addr Places address of clock period. 
U. 32 ne- Prints unsigned “ to console. 
? 35 addr E -- Prints what is at addr to cncl. Tasking and Event Scheduling 
CN M cE- Outputs string to console. 
ENIT 43 a E--. Outputs ASCII chr to console. Task definition 
SP 43 — k -- ace to console screen. 
CR 43 — f -- CRLF to console screen. TASK 53 TASK task token Creates task and links to token. 
ere 67 


Task Scheduling 


Lock 595 — k 
UNLOCK 35 — k — 
START 53 --E 4 
STOP 33 — f 3 
RUN 335 — k 5 

IN 53 — k 0 

533 — E 2 

EVERY 933 — E 1 

TI S nE d 
TS SB nE d 

In 53 n k d 

TH 53 n F d 

Ib 53 un k 4 

TW S nE ad 

TY 53 ned 

Miscelaneous 

TON 55 --E-- 
TOFF 595 --E-- 
BACK 55 BACK token 
NUL 55 — Ek 
Cossents 

( 50 --E-- 
Editing 

SHIFI/JEDIT 15 Editor 

{- 15 Editor 
7 15 Editor 
U 15 Editor 
-} 15 Editor 
SHIFT/9 15 Editor 
SHIFT/4 15 Editor 
SHIFT/DELETE 15 Editor 
SHIFT/3 16 Editor 
SHIFT/2 16 Editor 
SHIFT/Q 17 Editor 
CPL 7 --€&-- 
EDFF 11 — Eo 
Dictionary Manageaent 
ALLOT U nE- 
VLIST 34 -E~ 
FENCE 4B FENCE token 
FORGET 48 FORGET token 
z 50 — ’ token addr 
’ 50 n E aa 

C 50 b E 
here 50 — : addr 
1 590 # addr 
READ $ ll, 


Locks out higher prio. tasks. 
Unlocks higher Bley tasks. 
Places START 10 for task. 
Places STOP [D8 for task. 
Places RUN identifier for task. 
Places IN identifier for task. 
Places AT identifier for task. 
Places EVERY Ibs for task, 
Extends n ticks into double. 
Cosputes n Seconds in ticks. 
Cosputes n Minutes in ticks. 
Cosputes n Hours in ticks. 
Cosputes n Days in ticks. 
Coaputes n Weeks in ticks. 
Coaputes n Years in ticks. 


Turns wara reset task flag on. 
Turns wara reset task flag off. 
Makes token background task. 
Nul prograna for BACK. 


Precedes cossent up to). 


Enables and toggel’s in / out edit. 
Moves cursor left one position. 
Moves cursor up one line. 

Moves cursor down one line. 
Moves cursor 1855 one position. 
Inserts blank line to cursor. 
Deletes cursor line. 

Deletes cursor character. 

br abs cursor line to PAD. 
Inserts PAD line to cursor line. 
Coepiles cursor line. 

Compiles edit screen. 

Disables edit screen. 


` Reserves n bytes in dictionary. 


Lists glad to console. 
Protects token from FORGET. 
Truncates dict. to before token. 
Leaves code address of token. 
Adds word to dictionary streas. 
Adds byte to dictionary streae. 
Fetches contents of H. Cons 
eaves addr Of head pointer. Vaf 


A 
yey s addr af tail paiater, var 


reates a diet header "token" 


HESS 


1 l. 1 50 l.)] ies-token 

t IRM 50 — E 
Systea Manageaent 
AUTO 19 — E -- 
SLOW 18 — f — 
FAST 19 --E-- 
MEN 34 Len 
WARN 12 2? E-- 
COLD 11 2 E-- 

1  FBUF 30 — E addr 
CPU 2 --E-- 
+0R6 36 ul E addr 
Extension of Tree-Forth 
UPDATE App C -- E -- 
INIT App C INIT token 
PASS App € - E 


Cospiles issediate token. 
Makes token iseediate, 


Enters auto sode. 
Unconditionaly enters slow node, 
Unconditionaly enters fast eode. 
Calculates available aesory, 
Executes a ware reset. 

Executes a cold reset. 

Frase buffer address. Int 
Identifies processor type. 
Generates syste variable addr. 


Updates extension pointers. 
Runs token on power up. (Special) 
Lisited WARM reset. 


Note. Any operator preceeded by an asteric "8° is an ieeediate keyword 
on entering reguardless of whether it is being 


t 
and will execute iapediately u 
cospiled in a definition or no 


f 


THE END 


